Cleanup docs and make them RTD themed

NERSC · Feb 17, 2020 · 638d635 · 638d635
1 parent 2a75bbf
commit 638d635
Show file tree

Hide file tree

Showing 10 changed files with 84 additions and 35 deletions.
diff --git a/doc/advanced.rst b/doc/advanced.rst
@@ -0,0 +1,13 @@
+Advanced Topics
+===============
+
+.. toctree::
+   :titlesonly:
+   :maxdepth: 2
+
+   mpi/mpich_abi
+   wlm/slurm
+   modules
+   sshd
+   import
+
diff --git a/doc/api/authentication.rst b/doc/api/authentication.rst
@@ -20,17 +20,17 @@ that case the originating request must include a more extensive
 Format of the "authentication" HTTP header
 ------------------------------------------
 * _Non-privileged requests:_ munge encoded empty string
-* _Privileged requests:_ munge encoded JSON document including one or more 
-  credentials for the remote image resources
+* _Privileged requests:_ munge encoded JSON document including one or more credentials for the remote image resources
 
 JSON document format:
 *********************
 
+.. code-block:: json
+
    {
        "authorized_locations": {
            "default":"username:password",
-           "otherloc":"username:password",
-           ...
+           "otherloc":"username:password"
        }
    }
 

diff --git a/doc/conf.py b/doc/conf.py
@@ -54,9 +54,9 @@
 # built documents.
 #
 # The short X.Y version.
-version = u'16.05.01'
+version = u'18.03.01'
 # The full version, including alpha/beta/rc tags.
-release = u'16.05.01'
+release = u'18.03.01'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
@@ -108,7 +108,7 @@
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
-html_theme = 'alabaster'
+html_theme = 'sphinx_rtd_theme'
 
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the

diff --git a/doc/import.md → doc/import.rst b/doc/import.md → doc/import.rst
@@ -1,10 +1,12 @@
-# Importing Images (beta)
+Importing Images (beta)
+=======================
 
 While Shifter is primarily designed to run images built using Docker, it also
 supports directly importing pre-prepared images.  Since some sites may not
 wish to support this or limit its usage, it requires extra configuration.
 
-## Security Considerations
+Security Considerations
+-----------------------
 
 Before enabling this feature, the administrator should understand the
 increased risks of allowing direct imports of images perpared outside
@@ -20,33 +22,37 @@ being included in the image.  When using the workload manager integration
 import users block xattrs since the mounts may be visible
 to processes running outside the runtime.
 
-## Approach
+Approach
+--------
 
 Importing images works by copying a pre-prepared image into the shared
 location, generating a pseudo-hash for the image, and adding an entry in
 the Shifter image list.
 
-## Enabling support
+Enabling support
+----------------
 
 To enable support, add an "ImportUsers" parameters into the top section of
 the imagemanager.json file.  This can be a list of user names (in JSON list
 format) or the keyword "all".  For example:
 
-~~~~
-...
-"ExpandDirectory": "/tmp/images/expand/",
-"ImportUsers":"all"
-"Locations": {
-...
-~~~~
+.. code-block:: json
+
+  {
+     "ExpandDirectory": "/tmp/images/expand/",
+     "ImportUsers":"all"
+     "Locations": {
+     }
+  }
 
 The fasthash script needs to be installed as `fasthash` in a location on
 the search path for the image gateway for local mode or in the search path
 on the remote system for remote mode.  This script generates a pseudo-hash
 for the image based on the contents of the image.
 
 
-## Usage
+Usage
+-----
 
 The user issuing the import most have the squashed image in a location that is
 accessible by the shifter user (e.g. the account used to run the gateway).
@@ -56,15 +62,15 @@ must be issued.  Here is an example of an import command to import the squashfs
 located at /tmp/image.squashfs and call it
 load_test:v1 in Shifter.
 
-~~~~bash
-curl -d '{"filepath":"/tmp/myimage.squashfs","format":"squashfs"}' \
-  -H "authentication: $(munge -n)" \
-  http://<imagegw>:5000/api/doimport/mycluster/custom/load_test:v1/
-~~~~
+.. code-block:: bash
+
+   curl -d '{"filepath":"/tmp/myimage.squashfs","format":"squashfs"}' \
+     -H "authentication: $(munge -n)" \
+     http://<imagegw>:5000/api/doimport/mycluster/custom/load_test:v1/
 
 Once an image is imported, it is run with Shifter like other images.
 The only difference is the type is "custom" instead of the default "docker".
 
-```bash
-shifter --image=custom:load_test:v1 /bin/app
-```
+.. code-block:: bash
+
+   shifter --image=custom:load_test:v1 /bin/app
diff --git a/doc/index.rst b/doc/index.rst
@@ -27,15 +27,16 @@ This is achieved by:
 Contents:
 
 .. toctree::
+   :titlesonly:
    :maxdepth: 2
 
    faq
    bestpractices
-   mpi/mpich_abi
-   install/centos6
-   install/cle6
-   install/manualinstallgpu
-   wlm/slurm
+   updating
+   install_guides
+   references
+   advanced
+   security
 
 
 

diff --git a/doc/install/imagegw.rst b/doc/install/imagegw.rst
@@ -20,6 +20,8 @@ have write access to a file system that is visible to all nodes on the compute
 cluster.  Here is a sample configuration.  Notice that Mongo would need
 to run on the same service node.
 
+.. code-block:: json
+
     {
         "DefaultImageLocation": "registry-1.docker.io",
         "DefaultImageFormat": "squashfs",
@@ -63,6 +65,8 @@ configured on the target system with a copy of the private key available to
 the special account on the Image Gateway.  Here is a sample configuration for
 this deployment model.
 
+.. code-block:: json
+
     {
         "DefaultImageLocation": "registry-1.docker.io",
         "DefaultImageFormat": "squashfs",

diff --git a/doc/install/manualinstallgpu.rst b/doc/install/manualinstallgpu.rst
@@ -16,10 +16,10 @@ We use this approach and solve the practical details for allowing container port
 
 
 Installation
-============
+------------
 
 Shifter Runtime
----------------
+***************
 
 Most often, Shifter's runtime should be installed on the frontend node as well as on the compute nodes. However, it is also possible to install shifter solely on the compute nodes and use shifter on the frontend node through Slurm.
 

diff --git a/doc/install_guides.rst b/doc/install_guides.rst
@@ -0,0 +1,13 @@
+Installation Guides
+===================
+.. toctree::
+   :maxdepth: 1
+
+   install/centos6
+   install/centos7
+   install/centos7_ppc64le
+   install/cle6
+   install/manualinstallgpu
+   install/imagegw
+
+
diff --git a/doc/references.rst b/doc/references.rst
@@ -0,0 +1,12 @@
+References
+==========
+
+
+.. toctree::
+   :titlesonly:
+   :maxdepth: 2
+
+   Shifter Command-line  <command/shifter>
+   config/udiRoot.conf
+   api/authentication
+
diff --git a/doc/updating.rst b/doc/updating.rst
@@ -82,7 +82,7 @@ using, be sure to update the port in sshd_config and ssh_config to use port
 1204 (or some other port that makes sense for your site).
 
 Image Manager API
-=================
+-----------------
 We recommend that you install and run the image manager via gunicorn.  This is
 much more scalable than the Flask development server started by the older (now
 considered for debug-only) imagemngr.py.