add tabs in user guide and admin sections

MolSSI · Aug 20, 2023 · b867fb4 · b867fb4
1 parent 1cb609f
commit b867fb4
Show file tree

Hide file tree

Showing 10 changed files with 588 additions and 374 deletions.
diff --git a/docs/requirements.txt b/docs/requirements.txt
@@ -2,6 +2,7 @@ sphinx_design
 pydata_sphinx_theme
 sphinx
 autodoc-pydantic
+sphinx-copybutton
 -e ../qcportal
 -e ../qcfractalcompute
 -e ../qcfractal

diff --git a/docs/source/admin_guide/setup.rst b/docs/source/admin_guide/setup.rst
@@ -23,10 +23,14 @@ The QCFractal server can be installed via `conda/anaconda <https://www.anaconda.
 or `mamba <https://github.com/mamba-org/mamba>`_. The packages exist under the
 `QCArchive organization <https://anaconda.org/QCArchive>`_ on Anaconda.
 
-.. code-block:: bash
+.. tab-set::
 
-    $ conda create -n qcf_server qcfractal postgresql -c qcarchive/label/next
-    $ conda activate qcf_server
+  .. tab-item:: SHELL
+
+    .. code-block:: bash
+
+        conda create -n qcf_server qcfractal postgresql -c qcarchive/label/next
+        conda activate qcf_server
 
 
 Setting up the server
@@ -35,10 +39,14 @@ Setting up the server
 You generally want to keep all files related to the QCFractal server in a single directory.
 So we are going to create a directory, and then initialize a configuration file there.
 
-.. code-block:: bash
+.. tab-set::
+
+  .. tab-item:: SHELL
 
-    $ mkdir qcf_server
-    $ qcfractal-server --config=qcf_server/qcf_config.yaml init-config
+    .. code-block:: bash
+
+        mkdir qcf_server
+        qcfractal-server --config=qcf_server/qcf_config.yaml init-config
 
 This creates an example configuration file. You are now free to change those settings as
 needed - see :ref:`server_configuration`.
@@ -57,25 +65,37 @@ Some fields are likely to be changed
 Now we are ready to initialize the database. This creates the database directory structure and files,
 as well as the actual postgres database and tables for QCFractal.
 
-.. code-block:: bash
+.. tab-set::
+
+  .. tab-item:: SHELL
 
-    $ qcfractal-server --config=qcf_server/qcf_config.yaml init-db
+    .. code-block:: bash
+
+        qcfractal-server --config=qcf_server/qcf_config.yaml init-db
 
 
 Before starting the server, it doesn't hurt to check the configuration to make sure it matches
 your expectations.
 
-.. code-block:: bash
+.. tab-set::
+
+  .. tab-item:: SHELL
+
+    .. code-block:: bash
 
-    $ qcfractal-server --config=qcf_server/qcf_config.yaml info
+        qcfractal-server --config=qcf_server/qcf_config.yaml info
 
 
 Now we may start the server! This will run the server in the foreground, so you can not use your terminal anymore.
 You can place it in the background with **screen** or any other utilities if needed.
 
-.. code-block:: bash
+.. tab-set::
+
+  .. tab-item:: SHELL
+
+    .. code-block:: bash
 
-    $ qcfractal-server --config=qcf_server/qcf_config.yaml start
+        qcfractal-server --config=qcf_server/qcf_config.yaml start
 
 To stop a running server, you can use **Ctrl-C**.
 

diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -46,6 +46,7 @@
     'sphinx.ext.napoleon',
     'sphinx_design',
     'sphinxcontrib.autodoc_pydantic',
+    'sphinx_copybutton'
 ]
 
 # Some options

diff --git a/docs/source/user_guide/client_setup.rst b/docs/source/user_guide/client_setup.rst
@@ -8,10 +8,14 @@ The QCPortal package can be installed via `conda/anaconda <https://www.anaconda.
 or `mamba <https://github.com/mamba-org/mamba>`_. The packages exist under the
 `QCArchive organization <https://anaconda.org/QCArchive>`_ on Anaconda.
 
-.. code-block:: bash
+.. tab-set::
 
-    $ conda create -n qcportal qcportal -c qcarchive/label/next
-    $ conda activate qcportal
+  .. tab-item:: SHELL
+
+    .. code-block:: bash
+
+        conda create -n qcportal qcportal -c qcarchive/label/next
+        conda activate qcportal
 
 
 .. _qcportal_setup_configfile:
@@ -33,11 +37,15 @@ Single Server
 If you are only interested in a single server, then the configuration file can just
 contain the address and user information.
 
-.. code-block:: yaml
+.. tab-set::
+
+  .. tab-item:: CONFIG FILE
+
+    .. code-block:: yaml
 
-  address: https://qcademo.molssi.org
-  username: your_username
-  password: Secret_Password
+      address: https://qcademo.molssi.org
+      username: your_username
+      password: Secret_Password
 
 Multiple Servers
 ~~~~~~~~~~~~~~~~
@@ -46,17 +54,21 @@ If you are working with multiple servers, then the configuration file contains s
 the address and other options. The name is arbitrary and is for the user to
 differentiate between different servers.
 
-.. code-block:: yaml
+.. tab-set::
 
-    qca_demo_server:
-      address: https://qcademo.molssi.org
-      username: your_username
-      password: Secret_Password
+  .. tab-item:: CONFIG FILE
+
+    .. code-block:: yaml
 
-    group_server:
-      address: http://192.168.123.123:7777
-      username: your_username
-      password: Secret_Password
+        qca_demo_server:
+          address: https://qcademo.molssi.org
+          username: your_username
+          password: Secret_Password
+
+        group_server:
+          address: http://192.168.123.123:7777
+          username: your_username
+          password: Secret_Password
 
 The path to this file and the section name can passed to the
 :meth:`~qcportal.client.PortalClient.from_file` function.
diff --git a/docs/source/user_guide/connecting_qcportal.rst b/docs/source/user_guide/connecting_qcportal.rst
@@ -9,24 +9,36 @@ Connecting to the server is handled by the constructor of the :class:`~qcportal.
 The first parameter is the address or URI of the server you with to connect to (including ``http``/``https``).
 If no address is given, then by default the client will connect to the public, MolSSI-hosted server.
 
-  >>> from qcportal import PortalClient
-  >>> client = PortalClient()
-  >>> print(client.server_name)
-  MolSSI Public QCArchive Server
+.. tab-set::
+
+  .. tab-item:: PYTHON
+
+    >>> from qcportal import PortalClient
+    >>> client = PortalClient()
+    >>> print(client.server_name)
+    MolSSI Public QCArchive Server
 
 However, you can specify the address of another server. Here we connect to the MolSSI-hosted
 public demonstration server
 
-  >>> from qcportal import PortalClient
-  >>> client = PortalClient("https://qcademo.molssi.org")
-  >>> print(client.server_name)
-  MolSSI QCArchive Demo Server
+.. tab-set::
+
+  .. tab-item:: PYTHON
+
+    >>> from qcportal import PortalClient
+    >>> client = PortalClient("https://qcademo.molssi.org")
+    >>> print(client.server_name)
+    MolSSI QCArchive Demo Server
 
 Servers may require a username and password to connect or to perform certain actions;
 these can also be specified in the constructor.
 
-  >>> from qcportal import PortalClient
-  >>> client = PortalClient("https://my.qcarchive.server", username='grad_student_123', password='abc123XYZ')
+.. tab-set::
+
+  .. tab-item:: PYTHON
+
+    >>> from qcportal import PortalClient
+    >>> client = PortalClient("https://my.qcarchive.server", username='grad_student_123', password='abc123XYZ')
 
 For a description of the other parameters, see :class:`~qcportal.client.PortalClient`.
 
@@ -44,18 +56,22 @@ To use this file, construct the client using the
 If no path is passed to this function, then the current working directory
 and then the ``~/.qca`` directory are search for ``qcportal_config.yaml``.
 
-.. code-block:: py3
+.. tab-set::
 
-    # A file containing a single server, file stored in working directory or ~/.qca
-    >>> from qcportal import PortalClient
-    >>> client = PortalClient.from_file()
-    >>> print(client.server_name)
-    MolSSI QCArchive Demo Server
+  .. tab-item:: PYTHON
 
-    # Manually specify a path to the config file
-    >>> client = PortalClient.from_file('group_server', '/path/to/config')
-    >>> print(client.server_name)
-    Professor's Group Server
+    .. code-block:: py3
+
+        # A file containing a single server, file stored in working directory or ~/.qca
+        >>> from qcportal import PortalClient
+        >>> client = PortalClient.from_file()
+        >>> print(client.server_name)
+        MolSSI QCArchive Demo Server
+
+        # Manually specify a path to the config file
+        >>> client = PortalClient.from_file('group_server', '/path/to/config')
+        >>> print(client.server_name)
+        Professor's Group Server
 
 
 Viewing server metadata
@@ -65,30 +81,33 @@ Some metadata about the server is stored in the client object. The metadata incl
 name and version, as well as limits on API calls. This also contains any Message-of-the-Day (MOTD) that
 the server administrator wishes to include.
 
-
-.. code-block:: py3
-
-    >>> from qcportal import PortalClient
-    >>> client = PortalClient('https://qcademo.molssi.org')
-    >>> print(client.server_info)
-    {'name': 'MolSSI QCArchive Demo Server',
-     'manager_heartbeat_frequency': 1800,
-     'version': '0.50b4.post4+ged0d0270',
-     'api_limits': {'get_records': 1000,
-      'add_records': 500,
-      'get_dataset_entries': 2000,
-      'get_molecules': 1000,
-      'add_molecules': 1000,
-      'get_managers': 1000,
-      'manager_tasks_claim': 200,
-      'manager_tasks_return': 10,
-      'get_server_stats': 25,
-      'get_access_logs': 1000,
-      'get_error_logs': 100,
-      'get_internal_jobs': 1000},
-     'client_version_lower_limit': '0',
-     'client_version_upper_limit': '1',
-     'motd': ''}
+.. tab-set::
+
+  .. tab-item:: PYTHON
+
+    .. code-block:: py3
+
+        >>> from qcportal import PortalClient
+        >>> client = PortalClient('https://qcademo.molssi.org')
+        >>> print(client.server_info)
+        {'name': 'MolSSI QCArchive Demo Server',
+        'manager_heartbeat_frequency': 1800,
+        'version': '0.50b4.post4+ged0d0270',
+        'api_limits': {'get_records': 1000,
+          'add_records': 500,
+          'get_dataset_entries': 2000,
+          'get_molecules': 1000,
+          'add_molecules': 1000,
+          'get_managers': 1000,
+          'manager_tasks_claim': 200,
+          'manager_tasks_return': 10,
+          'get_server_stats': 25,
+          'get_access_logs': 1000,
+          'get_error_logs': 100,
+          'get_internal_jobs': 1000},
+        'client_version_lower_limit': '0',
+        'client_version_upper_limit': '1',
+        'motd': ''}
 
 
 Next steps