docs: reorganize top-level (#210)

* reorganize top-level of docs * use pydata layout (as on aiida-core) * add logo * add "Edit on Github" button * add prominent link back to materialscloud.org/aiidalab
aiidalab · Sep 14, 2021 · e0c9ca1 · e0c9ca1
1 parent c7f8f66
commit e0c9ca1
Show file tree

Hide file tree

Showing 8 changed files with 121 additions and 76 deletions.
diff --git a/docs/source/_static/aiidalab_logo.png b/docs/source/_static/aiidalab_logo.png
diff --git a/docs/source/maintain/index.rst → docs/source/admin/index.rst b/docs/source/maintain/index.rst → docs/source/admin/index.rst
@@ -1,6 +1,27 @@
-*****************
-Maintain AiiDAlab
-*****************
+*******************
+Administrator guide
+*******************
+
+This guide explains how to deploy and manage AiiDAlab servers for multiple users.
+See :ref:`usage:run-locally` for how to run the AiiDAlab docker container locally (e.g. for testing purposes).
+
+Multi-user deployment
+=====================
+
+Single-server deployment
+-------------------------
+
+For medium-sized deployments (a handful of users), an AiiDAlab multi-user server can deployed on a single (virtual or bare-metal) machine.
+
+Since deploying a multi-user server requires additional packages, such as `JupyterHub <https://jupyter.org/hub>`__, `DockerSpawner <https://github.com/jupyterhub/dockerspawner>`__, `Apache HTTP Server <https://www.apache.org/>`__, and `Docker <http://www.docker.com>`__, we provide the ``aiidalab-server`` `Ansible <https://www.ansible.com/>`__ role which automates the setup of the server.
+Please see the `corresponding git repository <https://github.com/aiidalab/ansible-role-aiidalab-server>`__ for more information.
+
+
+Kubernetes deployment
+---------------------
+
+If you are expecting a large number of users (>50), consider deploying AiiDAlab on a scalable Kubernetes cluster.
+We provide `instructions and deployment scripts <https://github.com/aiidalab/aiidalab-k8s>`__ for this use case.
 
 Run a separate registry
 =======================

diff --git a/docs/source/app_development/index.rst b/docs/source/app_development/index.rst
@@ -1,8 +1,10 @@
 .. _develop-apps:
 
-#####################
-Develop AiiDAlab apps
-#####################
+###################
+App developer guide
+###################
+
+This guide explains how to get started with developing AiiDAlab apps.
 
 .. toctree::
     :maxdepth: 1

diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -82,6 +82,26 @@
 
 html_theme = "pydata_sphinx_theme"
 
+html_theme_options = {
+    "external_links": [
+        {"url": "https://www.materialscloud.org/aiidalab", "name": "AiiDAlab"}
+    ],
+    "github_url": "https://github.com/aiidalab/aiidalab",
+    "use_edit_page_button": True,
+}
+
+# for "edit on github" button
+html_context = {
+    "github_user": "aiidalab",
+    "github_repo": "aiidalab",
+    "github_version": "develop",
+    "doc_path": "docs/source",
+}
+
+# The name of an image file (relative to this directory) to place at the top
+# of the sidebar.
+html_logo = "_static/aiidalab_logo.png"
+
 
 def run_apidoc(_):
     """Runs sphinx-apidoc when building the documentation.

diff --git a/docs/source/deployment/index.rst b/docs/source/deployment/index.rst
diff --git a/docs/source/development/index.rst b/docs/source/development/index.rst
@@ -1,6 +1,8 @@
-****************
-Develop AiiDAlab
-****************
+*****************
+Development guide
+*****************
+
+This guide is intended for developers of the AiiDAlab platform itself and covers topics such as the overall architecture, release workflow, etc.
 
 Key AiiDAlab components
 =======================

diff --git a/docs/source/index.rst b/docs/source/index.rst
@@ -9,11 +9,10 @@ AiiDAlab builds on `AiiDA <https://www.aiida.net/>`_ as the computational workfl
 .. toctree::
    :maxdepth: 1
 
-   Deploy AiiDAlab <deployment/index>
-   Use AiiDAlab <usage/index>
-   Develop AiiDAlab apps <app_development/index.rst>
-   Maintain AiiDAlab <maintain/index.rst>
-   Develop AiiDAlab <development/index.rst>
+   usage/index
+   app_development/index
+   admin/index.rst
+   development/index
    API documentation <apidoc/aiidalab>
 
 

diff --git a/docs/source/usage/index.rst b/docs/source/usage/index.rst
@@ -1,6 +1,66 @@
-============
-Use AiiDAlab
-============
+==========
+User guide
+==========
+
+
+***************
+Access AiiDAlab
+***************
+
+As a user, you have two options to access AiiDAlab:
+
+ 1. Log into one of the `open AiiDAlab servers <https://materialscloud.org/aiidalab>`_.
+ 2. Run the AiiDAlab docker container on your local machine.
+
+.. _usage:run-locally:
+
+Run AiiDAlab locally
+====================
+
+Prerequisites
+-------------
+
+Linux or MacOS with `Docker installed <https://www.docker.com/get-started>`__
+
+
+Instructions
+------------
+
+Pull the AiiDAlab docker image from DockerHub and tag it so that the startup script recognizes it:
+
+   .. code-block:: console
+
+       $ docker pull aiidalab/aiidalab-docker-stack:latest
+       $ docker tag aiidalab/aiidalab-docker-stack:latest aiidalab-docker-stack:develop
+
+Clone the `AiiDAlab Docker Stack <https://github.com/aiidalab/aiidalab-docker-stack>`__ repository and enter the cloned directory:
+
+   .. code-block:: console
+
+       $ git clone https://github.com/aiidalab/aiidalab-docker-stack
+       $ cd aiidalab-docker-stack
+
+Start AiiDAlab by running:
+
+   .. code-block:: console
+
+       $ ./run.sh --no-build 8888 ~/aiidalab
+
+
+  * ``8888`` is the port under which the AiiDAlab web interface will be available.
+  * ``~/aiidalab`` is the **absolute** path to the directory that will be mounted as the persistent home directory inside the container.
+    If the directory does not exist, it will be created.
+
+The startup procedure can take a while, particularly when you run it for the first time.
+Once it is done, open the link provided at the bottom of the console in your web browser.
+You should now see the AiiDAlab home page.
+
+.. note::
+
+    The instructions above use the pre-built AiiDAlab docker image from DockerHub.
+    In order to build the image yourself (e.g. to apply modifications), simply run the script without the ``--no-build`` option::
+
+        ./run.sh 8888 ~/aiidalab
 
 
 ******************