Merge pull request #166 from openforcefield/user-guide

Add user guide to docs, restructure some other documentation pages
OpenFreeEnergy · Aug 18, 2023 · b831756 · b831756
2 parents 2dca4d0 + e40968b
commit b831756
Show file tree

Hide file tree

Showing 5 changed files with 478 additions and 56 deletions.
diff --git a/docs/conf.py b/docs/conf.py
@@ -24,6 +24,7 @@
     "sphinx.ext.autodoc",
     "sphinx.ext.napoleon",
     "sphinx.ext.githubpages",
+    "sphinx.ext.intersphinx"
 ]
 
 templates_path = ["_templates"]
@@ -46,6 +47,13 @@
     "yaml",
 ]
 
+intersphinx_mapping = {
+    'gufe': ('https://gufe.readthedocs.io/en/latest/', None),
+    'openfe': ('https://docs.openfree.energy/en/stable/', None),
+    'perses': ('https://perses.readthedocs.io/en/latest/', None),
+    'python': ('https://docs.python.org/3', None),
+}
+
 # -- Options for HTML output -------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
 

diff --git a/docs/deployment.rst b/docs/deployment.rst
@@ -1,3 +1,5 @@
+.. _deployment:
+
 ##########
 Deployment
 ##########
@@ -125,58 +127,3 @@ If your API services are deployed on resources outside AWS, you will need to giv
     The access key content itself.
 
 No additional setup is required for the object store.
-
-
-###########
-Maintenance
-###########
-
-*********
-Add Users
-*********
-
-To add a new user identity, you will generally use the ``alchemiscale`` CLI::
-
-
-    $ export NEO4J_URL=bolt://<NEO4J_HOSTNAME>7687
-    $ export NEO4J_USER=<NEO4J_USERNAME>
-    $ export NEO4J_PASS=<NEO4J_PASSWORD>
-    $
-    $ # add a user identity, with key
-    $ alchemiscale identity add -t user -i <user identity> -k <user key>
-    $
-    $ add one or more scopes the user should have access to
-    $ alchemiscale identity add-scope -t user -i <user identity> -s <org-campaign-project> -s ...
-
-To add a new compute identity, perform the same operation as for user identities given above, **but replace ``-t user`` with ``-t compute``**.
-Compute identities are needed by compute services to authenticate with and use the compute API.
-
-
-``docker-compose`` deployment
-=============================
-
-For a ``docker-compose``-based deployment, it is easiest to do the above using the same ``alchemiscale-server`` image the API services are deployed with::
-
-    $ docker run --rm -it --network docker_db -e NEO4J_URL=bolt://neo4j:7687 -e NEO4J_USER=<USER> -e NEO4J_PASS=<PASSWORD> \
-      <ALCHEMISCALE_DOCKER_IMAGE> identity add -t user \
-                                               -i <user identity> \
-                                               -k <user key>
-    $ docker run --rm -it --network docker_db -e NEO4J_URL=bolt://neo4j:7687 -e NEO4J_USER=<USER> -e NEO4J_PASS=<PASSWORD> \
-      <ALCHEMISCALE_DOCKER_IMAGE> identity add-scope -t user \
-                                                     -i <user identity> \
-                                                     -s <org-campaign-project> -s ...
-
-The important bits here are:
-
-``--network docker_db``
-    We need to make sure the docker container we are using can talk to the database container.
-
-``-e NEO4J_URL=bolt://neo4j:7687 -e NEO4J_USER=<USER> -e NEO4J_PASS=<PASSWORD>``
-    We need to pass in these environment variables so that the container can talk to the database.
-    These should match the values set in ``.env``.
-
-
-*******
-Backups
-*******
-
diff --git a/docs/index.rst b/docs/index.rst
@@ -28,8 +28,10 @@ in particular the `OpenForceField`_ and `OpenFreeEnergy`_ ecosystems.
 
 
    ./overview
-   ./API_docs
+   ./user_guide
    ./deployment
+   ./operations
+   ./API_docs
 
 
 Indices and tables

diff --git a/docs/operations.rst b/docs/operations.rst
@@ -0,0 +1,53 @@
+##########
+Operations
+##########
+
+*********
+Add Users
+*********
+
+To add a new user identity, you will generally use the ``alchemiscale`` CLI::
+
+
+    $ export NEO4J_URL=bolt://<NEO4J_HOSTNAME>7687
+    $ export NEO4J_USER=<NEO4J_USERNAME>
+    $ export NEO4J_PASS=<NEO4J_PASSWORD>
+    $
+    $ # add a user identity, with key
+    $ alchemiscale identity add -t user -i <user identity> -k <user key>
+    $
+    $ add one or more scopes the user should have access to
+    $ alchemiscale identity add-scope -t user -i <user identity> -s <org-campaign-project> -s ...
+
+To add a new compute identity, perform the same operation as for user identities given above, **but replace ``-t user`` with ``-t compute``**.
+Compute identities are needed by compute services to authenticate with and use the compute API.
+
+
+``docker-compose`` deployment
+=============================
+
+For a ``docker-compose``-based deployment, it is easiest to do the above using the same ``alchemiscale-server`` image the API services are deployed with::
+
+    $ docker run --rm -it --network docker_db -e NEO4J_URL=bolt://neo4j:7687 -e NEO4J_USER=<USER> -e NEO4J_PASS=<PASSWORD> \
+      <ALCHEMISCALE_DOCKER_IMAGE> identity add -t user \
+                                               -i <user identity> \
+                                               -k <user key>
+    $ docker run --rm -it --network docker_db -e NEO4J_URL=bolt://neo4j:7687 -e NEO4J_USER=<USER> -e NEO4J_PASS=<PASSWORD> \
+      <ALCHEMISCALE_DOCKER_IMAGE> identity add-scope -t user \
+                                                     -i <user identity> \
+                                                     -s <org-campaign-project> -s ...
+
+The important bits here are:
+
+``--network docker_db``
+    We need to make sure the docker container we are using can talk to the database container.
+
+``-e NEO4J_URL=bolt://neo4j:7687 -e NEO4J_USER=<USER> -e NEO4J_PASS=<PASSWORD>``
+    We need to pass in these environment variables so that the container can talk to the database.
+    These should match the values set in ``.env``.
+
+
+*******
+Backups
+*******
+