Expand Documentation For Startup and Deployment (#24)

Author: BTSpeake

README.md

@@ -13,69 +13,33 @@
 [![Docs status](https://github.com/stfc/alc-ux/actions/workflows/ci-docs.yml/badge.svg?branch=main)](https://stfc.github.io/alc-ux/)
 [![DOI](badge)](https://zenodo.org/)
 
+Welcome to the ALC-UX resource repository.
+This repository contains all the information required to develop AiiDA/AiiDAlab applications
+for use with ALC software projects. It includes details on how to create and run the required 
+docker images to package additional components on top of the core AiiDAlab application, as 
+well as how to deploy these to users either locally or via a cloud host such as ADA. Additionally 
+included are example scripts and an example setup for a basic AiiDAlab plugin application. 
 
-This is an AiiDAlab application plugin for scientific workflows maintained by the [Ada Lovelace Center](https://adalovelacecentre.ac.uk/) (ALC). 
-The app is still in early development stage and any input/contributions are welcome. 
+## Documentation 
 
-
-## For Developers 
-
-### Style Checking
-
-This package uses pre-commit hooks to check for style consistency, to use these the ``pre-commit`` tool is required.
-This can be installed alongside the base package by running, 
-
-``` sh 
-pip install .[dev]
-```
-
-or separately via, 
-
-``` sh 
-pip install pre-commit 
-``` 
-
-Once installed run, 
-
-``` sh 
-pre-commit install 
-``` 
-
-in the base repository to enable the pre-commit hooks. 
-This will now run style and formatting checks on every commit. 
-
-### Testing 
-
-This package uses [pytest](https://docs.pytest.org/en/stable/) 
-to run all unit tests which is included in the ```[dev]``` optional 
-package dependencies. Once installed it can be run from the project root directory. 
-The CI workflows are configured to ensure all tests pass 
-before a pull request can be accepted into the main repository.
-It is important that any new additions to the code base are accompanied 
-by appropriate testing, maintaining a high code coverage. The coverage 
-can be checked via, 
-
-``` sh 
-pytest --cov=aiidalab_alc 
-``` 
-
-
-### Documentation 
+Access the full [documentation](https://stfc.github.io/alc-ux/).
 
 The documentation, including a User Guide, Developer Guide and an API reference, 
 is built using [sphinx](https://www.sphinx-doc.org/). The source 
 for which is contained in the ```docs/``` directory. At present 
-only the html generator has been fully tested. All required packages can 
-be installed alongside the core package via, 
+only the html generator has been fully tested.
+
+## Issues and Discussion
+
+This repository should provide a basic starting point for developing AiiDA/AiiDAlab plugins, 
+if there are any issues/questions please utilise the [issues](https://github.com/stfc/alc-ux/issues) and 
+[discussions](https://github.com/stfc/alc-ux/discussions) pages via the GitHub web interface. 
 
-``` sh 
-pip install .[docs]
-```
+## Existing AiiDAlab Projects 
 
-and then the documentation can be built using sphinx-build, 
+- [AiiDAlab ChemShell](https://github.com/stfc/aiidalab-chemshell)
 
-``` sh 
-sphinx-build -b html docs/source/ docs/build/html 
-```
+## Existing AiiDA Projects
 
-from the root directory. 
+- [aiida-mlip](https://github.com/stfc/aiida-mlip)
+- [aiida-chemshell](https://github.com/stfc/aiida-chemshell)

docker/aiidalab_chemshell/61_prepare-aiidalab_alc.sh

@@ -0,0 +1,12 @@
+#!/bin/bash 
+
+echo "INSTALLING AiiDAlab ALC app"
+cd "${HOME}"/apps
+wget https://github.com/stfc/alc-ux/archive/refs/heads/main.zip 
+unzip main.zip 
+rm -f main.zip 
+cd "${HOME}"/apps/alc-ux-main 
+pip install -q . 
+
+
+cd "${HOME}" 

docker/aiidalab_chemshell/Dockerfile

@@ -0,0 +1,19 @@
+# Use this for the latest official aiidalab image (Python 3.9)
+# FROM aiidalab/full-stack:latest 
+# Use this for a ported version of the above running on Python 3.10 
+FROM ghcr.io/stfc/alc-ux/base:py310  
+
+USER root
+ 
+# Install some extra required dendencies to speed up start up 
+RUN pip install aiidalab_widgets_base --no-cache-dir --no-user
+
+# Install alc aiida plugins 
+RUN pip install aiida-chemshell aiida-mlip --no-cache-dir --no-user  
+
+# This will install alc-ux on container start up 
+COPY 61_prepare-aiidalab_alc.sh /usr/local/bin/before-notebook.d/
+
+USER ${NB_UID}
+WORKDIR ${HOME}
+

docs/source/conf.py

@@ -10,7 +10,7 @@
 # -- Project information -----------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
 
-project = 'AiiDAlab ALC App'
+project = 'ALC AiiDAlab Guides'
 copyright = '2025, Ada Lovelace Center'
 author = 'Dr. Benjamin T. Speake'
 

docs/source/dev_docs/aiidalab_app_design.rst

@@ -8,15 +8,90 @@ the start banner for the plugin. From here each page defined within the applicat
 described by a jupyter notebook (\*.ipynb) file which may call components from the 
 core python package. 
 
-Model-View-Controller Paradigm
+
+Core Requirements
+-----------------
+
+Project Meta-Data
+~~~~~~~~~~~~~~~~~
+
+AiiDAlab uses the python style ``setup.cfg`` configuration file to define project meta-data which 
+it parses and associates with the plugin inside the AiiDAlab interface. This file must be 
+present within the plugins root directory or within a special ``.aiidalab`` directory under the 
+project root. Within it all the required meta-data can be specified such as project name, description,
+version number etc. More detail on the available and required meta-data inputs can be found 
+`here <https://aiidalab.readthedocs.io/en/latest/app_development/publish.html>`_ .
+
+Start Banner
+~~~~~~~~~~~~
+
+To be displayed in the core AiiDAlab home interface a plugin must contain a start banner, which can 
+either be defined in a python file (``start.py``) or a markdown file (``start.md``). This is the main 
+interface from the AiiDAlab home page to your developed plugin so should contain any relevant logos 
+and navigation buttons for the plugin. The example presented alongside this documentation in the 
+`github repo <https://github.com/stfc/alc-ux>`_ defines a python based approach with an embedded 
+HTML element which provides the application logo as a navigation button alongside a selection 
+of navigation buttons below the logo which all navigate to different components of the underlying 
+AiiDAlab plugin. 
+
+
+Main Application
+~~~~~~~~~~~~~~~~
+
+The main AiiDAlab plugin application will be written in jupyter notebook files ``.ipynb`` which 
+can either be self contained or for more complex UI project will reference an underlying python 
+library associated with the plugin. For the `example plugin <https://github.com/stfc/alc-ux>`_ 
+provided the main application page is defined in ``main.ipynb`` and refers to the ``aiidalab_alc`` 
+python library which contains all the required UI elements and how they interact with each other
+and the user. This library is defined in ``src/aiidalab-alc/`` and has various components that 
+each contribute to different aspects of the AiiDAlab plugins UI. 
+
+
+Making Your App Discoverable
+----------------------------
+
+When installing new plugins via the AiiDAlab plugin manager interface, plugins will be installed 
+and configured into the correct directories to be picked up by the AiiDAlab home page. However, 
+when developing plugins it is often required to manually manipulate these directories to make 
+sure your in-development application can be found and displayed by AiiDAlab. By default AiiDAlab 
+will create an ``apps`` directory within the home space of the container running the jupyter server
+instance. This is where all AiiDAlab plugin apps reside and where the home app looks to determine 
+which plugins are available. The process for AiiDAlab to install an application typically follows 
+as first checkout a specific release version of the plugin's code from its online host e.g. GitHub 
+into the ``apps`` folder. Following this it will run a pip install within the root source directory 
+of the plugin if required to install the required backend python UI package. 
+
+
+General Plugin Design Concepts
 ------------------------------
 
+Model-View-Controller Paradigm
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
 It is recommended that an AiiDAlab plugin follows the widely recognised Model-View-Controller 
 design paradigm for UI development. 
 The core UI package will use ``IPywidgets`` (or aiidalab's own pre-configured widgets) to display 
-the various UI components that a user will interact with. This defines the *view* for the application.
-The data that is being handled should exist seperate to any visual components that are part 
-of the applications *view* layer. They are handled by the ``traitlets`` python packages and can 
-be dynamically linked to user inputs through the *view* layer but should exist indendantly, thus 
+the various UI components that a user will interact with (described later). This defines the 
+*view* for the application. The data that is being handled should exist seperate to any visual 
+components that are part of the applications *view* layer. They are handled by the ``traitlets``
+python packages and can be dynamically linked to user inputs through the *view* layer but should exist indendantly, thus 
 defining the *model* layer. The controller layer is an optional additional layer that defines user 
-controll over that application that doesn't directly interact with any of the stored data. 
+controll over that application that doesn't directly interact with any of the stored data. 
+
+
+Widgets
+~~~~~~~
+
+Jupyter notebook based GUI's rely on components called widgets, often (but not exclusively) provided 
+by a library called `IPywidgets <https://ipywidgets.readthedocs.io/en/stable/>`_\. These form the core 
+UI elements that can be used as building blocks to create your application. They provide widgets for 
+formatting such as vertical/horizontal layout boxes, as well as different forms of input/output or 
+interaction interfaces, such as text display/input boxes, drop down lists or buttons. These can be 
+combined to build a complex GUI application. 
+
+In addition to the core widgets provided by IPywidgets, AiiDAlab provides several of its own widgets 
+specifically tailored for interacting with AiiDA components such as data structures and the database 
+itself. These are provided in the *aiidalab-widgets-base* python package and are documented 
+`here <https://aiidalab-widgets-base.readthedocs.io/en/latest/>`_\.
+
+

docs/source/dev_docs/containers.rst

@@ -1,3 +1,5 @@
+.. _developing_containers:
+
 Developing With Docker Containers
 =================================
 

docs/source/dev_docs/index.rst

@@ -1,11 +1,38 @@
 Developer Guide
 ===============
 
-Welcome to the ALC AiiDAlab app's developer guide. 
+Welcome to the developer's guide to AiiDAlab applications for the ALC. 
+
+This document contains all the information required to develop AiiDA/AiiDAlab applications
+for use with ALC software projects. It includes details on how to create and run the required 
+docker images to package additional components on top of the core AiiDAlab application, as 
+well as how to deploy these to users either locally or via a cloud host such as ADA.
+
+Introduction
+============
+
+AiiDAlab is a web based graphical user interface (GUI) for the popular scientific workflow 
+management software package AiiDA. It presents a step-by-step approach to defining complex 
+workflows utilising the relevant AiiDA plugins for the core computation. It is based on 
+the ``appmode`` plugin for jupyter notebooks, enabling complex UI elements to be hosted 
+within a web hosted jupyter notebook environment. This abstracts away many of the more 
+challenging concepts of the AiiDA workflow itself whilst providing user friendly UI 
+controls to interact with the provided plugins. 
+
+This guide aims to help developers get started with AiiDAlab plugin design and 
+deployment across the wide variety of software applications developed within 
+the ALC and STFC.  
+
+Any questions can be directed to the `discussions <https://github.com/stfc/alc-ux/discussions>`_
+page on GitHub or to benjamin.speake@stfc.ac.uk. 
+
+
+Contents
+========
 
 .. toctree::
    :maxdepth: 2
 
-   intro 
+   aiidalab_app_design
    containers
-   aiidalab_app_design
+   startup_and_deployment