This splits the software documentation into many smaller rst files wh…

…ich are much more manageable, with their own easier to find rendered pages.

Closes #61

Whilst splitting this file into many smaller files, a number of additions and changes were made to the documentation, including:

+ Adds (basic) documentation for:
  + IBM XL compilers (Closes #61)
  + Amber (Part of #78)
  + EMAN2
  + GRACE
  + Gromacs (Closes #37, part of #79)
  + NAMD
  + OpenMM
  + PLUMED
  + Singularity (Apptainer) (Closes #49)
  + Generic python information, with more detailed conda usage (Closes #47)
  + nvidia-smi (Closes #75)
  + HECBioSim project
  + IBM Collaboration project
  + Boost Module
  + FFTW module
  + NVTX library
  + PLUMED library
  + VTK
  + CMake
  + Make
+ Creates new `guides` section
  + Migrates the `profiling` documentation into the guides section
  + Migrates the `wanderings` about CUDA into the guides section
+ Adds some notes/warnings about potential WMLCE + RHEL 8 incompatibility. Larger changes still required (#63)
+ CSS/JS/_templates changes for a useful sidebar with the bootstrap theme with split source files
  + New issue #87 opened to consider replacing the theme to an actively maintained theme.
+ Removes relations.html from the sidebar, as styling issues were difficult to resolve nicely (Closes #77)
+ Adds sphinxext-rediraffe plugin for redirects for moved .html files (see conf.py)
+ Assorted RST improvements (links, crossrefs, quoteblocks, code-block, note, etc.)
+ Clarify module loads for RHEL 7 vs RHEL 8 where appropriate (Part of #73).
+ Assorted other improvements throughout the documentation
+ Adds the sphinx-copybutton plugin, for easy to copy code-block contents.

History was a little messy, so has been squashed to avoid `.git` bloat.

.gitignore

@@ -1,3 +1,8 @@
 .DS_Store
 _build/
 html/
+# Ignore directory created by vscode.
+.vscode/
+# ignore commonly used venv directories within the source repo.
+venv*/
+.venv*/

_static/css/custom.css

@@ -5,6 +5,9 @@
   --deep-blue-color: #054C91;
   --cool-grey-10-color: #63666A;
   --cool-grey-6-color: #A7A8AA;
+  --cool-grey-5-color: #b1b3b3;
+  --cool-grey-4-color: #bbbcbc;
+  --cool-grey-3-color: #c8c9c7;
   --cool-grey-2-color: #D0D0CE;
   --cool-grey-2-lighter-color: #E1E1E0; /* equivalent of Cool grey 2 with alpha 0.5 */
   --cool-grey-2-lightest-color: #F1F1F0; /* equivalent of Cool grey 2 with alpha 0.3 */
@@ -16,6 +19,10 @@ body {
     color: var(--cool-grey-10-color);
 }
 
+blockquote {
+  font-size: 17px;
+}
+
 h1, .h1, h2, .h2, h3, .h3 {
     color: var(--deep-blue-color);
 }
@@ -142,6 +149,50 @@ code {
   text-align: right;
 }
 
+/* Custom toctree highlighting.*/
+
+.bs-sidenav {
+  /* Remove padding so link formatting behaves as intended. */
+  padding-top: 0px;
+  padding-bottom: 0px;
+  overflow: hidden;
+}
+
+.bs-sidenav .nav.current li.current {
+  background: var(--cool-grey-2-color);
+  background: var(--cool-grey-2-lighter-color);
+}
+
+.bs-sidenav li.toctree-l1.current > a,
+.bs-sidenav li.toctree-l1.current li.toctree-l2 > a,
+.bs-sidenav li.toctree-l1 .nav-list li.toctree-l2 > a {
+  background: var(--cool-grey-2-lighter-color);
+}
+
+.bs-sidenav li.toctree-l2.current > a,
+.bs-sidenav li.toctree-l2.current li.toctree-l3 > a,
+.bs-sidenav li.toctree-l2 .nav-list li.toctree-l3 > a {
+  background: var(--cool-grey-3-color);
+}
+
+.bs-sidenav li.toctree-l3.current > a,
+.bs-sidenav li.toctree-l3.current li.toctree-l4 > a,
+.bs-sidenav li.toctree-l3 .nav-list li.toctree-l4 > a {
+  background: var(--cool-grey-4-color);
+}
+
+.bs-sidenav .nav > li > a:hover,
+.bs-sidenav .nav > li > a:focus {
+  background-color: var(--cool-grey-2-lighter-color);
+}
+
+.bs-sidenav .nav li.current > a {
+  /* Mark current items in the tree bolder */
+  font-weight: 900;
+}
+
+
+/* Change colours of alert blocks */
 .alert-info {
     background-color: var(--deep-blue-color);
     border-color: var(--deep-blue-color);
@@ -249,7 +300,7 @@ select:-webkit-autofill:focus {
     color: #9e0000;  /* A dark red which provides good contrast against the orange background) */
 }
 
-
+/* Media query for screens <= 1160px */
 @media (max-width: 1160px) {
   .navbar-header {
       float: none;

_static/js/custom.js

@@ -0,0 +1,20 @@
+// The sphinx-bootstrap-theme handles the {{ toctree() }} content generates different markup for global and local toctree content. This JS applies the `current` css class to list items for internal references on page load and if any internal links are clicked.
+$(document).ready(function() {
+    // On page load, mark localtoc elements as current if appropriate
+    $('.bs-sidenav .nav li > a.reference.internal').each(function() {
+        if (this.href === window.location.href) {
+            $(this).parent().addClass('current');
+            $(this).parents('.bs-sidenav li').addClass('current')
+        }
+    });
+    // on click of an internal reference in the toctree, adjust use of the current css class in the sidebar as appropriate
+    $('.bs-sidenav .nav li > a.reference.internal').click(function() {
+        // Remove the current class from others
+        $('.nav li').has("a.reference.internal").removeClass('current');
+        // Mark the new selected link as current.
+        $(this).parent().addClass("current");
+        // Mark parents 
+        $(this).parents('.bs-sidenav li').addClass('current')
+
+    });
+});

_templates/sidebartoc.html

@@ -0,0 +1,3 @@
+{{ toctree(collapse=True, maxdepth=-1, includehidden=False) }}
+<!-- {%- if display_toc %} -->
+<!-- {%- endif %} -->

conf.py

@@ -11,7 +11,12 @@
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
-extensions = []
+extensions = [
+    'sphinxcontrib.fulltoc',
+    "sphinxext.rediraffe",
+    'sphinx.ext.mathjax',
+    'sphinx_copybutton'
+]
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
@@ -26,7 +31,10 @@
 
 # General information about the project.
 project = u'Bede Documentation'
-copyright = u'2020, N8 CIR'
+# Extract the year from the current time.
+import datetime
+year = datetime.datetime.now().year
+copyright = f'{year}, N8 CIR'
 author = u'N8 CIR'
 
 # The version info for the project you're documenting, acts as replacement for
@@ -48,7 +56,7 @@
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
 # This patterns also effect to html_static_path and html_extra_path
-exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store', 'README.rst', "common/*.rst"]
+exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store', 'README.rst', "common/*.rst", '**.inc.rst', 'venv*', '.venv*']
 
 # The name of the Pygments (syntax highlighting) style to use.
 pygments_style = 'sphinx'
@@ -57,7 +65,6 @@
 todo_include_todos = False
 
 ## Added by CA to get MathJax rendering loaded
-extensions = ['sphinx.ext.mathjax']
 mathjax_path='https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js'
 
 
@@ -73,9 +80,9 @@
         ("Usage", "usage/index"),
         ("Hardware", "hardware/index"),
         ("Software", "software/index"),
-        ("Profiling", "profiling/index"),
+        ("Guides", "guides/index"),
         ("Training", "training/index"),
-        ("User Group", "bug/index"),
+        ("User Group", "user-group/index"),
         ("FAQ", "faq/index"),
     ],
 
@@ -86,25 +93,23 @@
     'navbar_pagenav': False,
     'source_link_position': "footer",
     'bootswatch_theme': "flatly",
+    'globaltoc_depth': 2,
+
 }
 html_static_path = ['_static']
 
-# Belt and braces: use both old and new sphinx syntax for custom CSS to make sure it loads
+# add custom css files
 html_css_files = [
     'css/custom.css',
 ]
-html_context = {
-    'css_files': [
-        '_static/css/custom.css'
-    ]
-}
 
+# Add custom js files
 html_js_files = [
     'https://use.fontawesome.com/c79ff27dd1.js',
     'js/rtd-versions.js',
+    'js/custom.js'
 ]
 
-
 # (Optional) Logo. Should be small enough to fit the navbar (ideally 24x24).
 # Path should be relative to the ``_static`` files directory.
 html_logo = '_static/images/logo-cmyk.png'
@@ -165,15 +170,34 @@
      'Miscellaneous'),
 ]
 
-
+# html sidebars issues warnings if multiple wildcard selectors match, so this is more verbsoe than it ideally would be. 
 html_sidebars = {
-    '**': ['localtoc.html', 'relations.html'],
+    '**': ['sidebartoc.html'],
     'index': [],
-    'search': []
+    'search': [],
+    'usage/index': ['localtoc.html'],
+    'hardware/index': [],
+    'training/index': ['localtoc.html'],
+    'guides/index': ['sidebartoc.html'],
+    'faq/index': ['localtoc.html'],
+    'user-group/index': [],
+    'faq/index': ['localtoc.html'],
+    'glossary/index': ['localtoc.html'],
+    'rhel8/index': ['localtoc.html'],
 }
 
 def setup(app):
     on_rtd = os.environ.get('READTHEDOCS', None) == 'True'
     if on_rtd:
         app.add_javascript('https://use.fontawesome.com/c79ff27dd1.js')
         app.add_javascript('js/rtd-versions.js')
+
+# Control use of the shphinx-rediraffe plugin to generate redirect files for moved documentation.
+# This is only viable for whole-pages, not for any bookmarks within a page unfortunately.
+rediraffe_redirects = {
+    "bug/index.rst": "user-group/index.rst",
+    "profiling/index.rst": "guides/nvidia-profiling-tools.rst",
+    "software/resnet50/bede-README-sbatch.rst": "software/applications/wmlce.rst",
+    "software/wanderings/wanderings-in-CUDALand.rst": "guides/wanderings/wanderings-in-CUDALand.rst",
+    "software/wanderings/Estimating-pi-in-CUDALand.rst": "guides/wanderings/Estimating-pi-in-CUDALand.rst",
+}

faq/index.rst

@@ -16,7 +16,7 @@ How can I acknowledge Bede in published or presented work?
 ----------------------------------------------------------------
 
 You can acknowledge Bede using the standard text that we provide. You can
-find this `here <https://bede-documentation.readthedocs.io/en/latest/usage/index.html#acknowledging-bede>`__.
+find this :ref:`here <usage-acknowledging-bede>`.
 
 How can I check my home directory quota?
 ----------------------------------------
@@ -34,7 +34,7 @@ You can use the following command:
 
 This tells me that, in this case, I have a limit of :code:`20480M`, and am 
 currently using :code:`79544K` across 1071 files. You can find more information
-about the Bede filesystems `here <https://bede-documentation.readthedocs.io/en/latest/usage/index.html#file-storage>`__.
+about the Bede filesystems :ref:`here <usage-file-storage>`.
 
 Where should I put project data?
 --------------------------------
@@ -53,14 +53,14 @@ How do I get started with Bede?
 -------------------------------
 
 The 'Using Bede' page runs through how to get registered, how to log in to the
-machine and how to run jobs, a link to this page can be found `here
-<https://bede-documentation.readthedocs.io/en/latest/usage/index.html>`__.
+machine and how to run jobs, a link to this page can be found :ref:`here
+<using-bede>`.
 
 How can I add my own software?
 ------------------------------
 
 It is recommended that you use spack to extend the installed software on the
-system, there are instructions on how to do this `here <https://bede-documentation.readthedocs.io/en/latest/software/index.html#environments>`__,
+system, there are instructions on how to do this :ref:`here <software-environments>`,
 along with further information about alternatives.
 
 

guides/cuda-investigations.rst

@@ -0,0 +1,8 @@
+Initial investigations with CUDA (under development)
+----------------------------------------------------
+
+.. toctree::
+   :maxdepth: -1
+
+   wanderings/wanderings-in-CUDALand
+   wanderings/Estimating-pi-in-CUDALand

guides/index.rst

@@ -0,0 +1,18 @@
+.. _guides:
+
+Guides
+======
+
+These provide guidance related to the use of Bede, such as the use of profiling tools.
+
+
+If you notice any omissions, errors or have any suggested changes to the documentation please create an `Issue <https://github.com/N8-CIR-Bede/documentation/issues>`__ or open a `Pull Request <https://github.com/N8-CIR-Bede/documentation/pulls>`__ on GitHub. 
+
+.. include:: ../common/rhel8-status.rst
+
+.. toctree::
+    :maxdepth: -1
+    :glob:
+
+    nvidia-profiling-tools.rst
+    ./*