Merge pull request #1786 from glotzerlab/update-docs

Documentation updates
glotzerlab · May 20, 2024 · 83b702e · 83b702e
2 parents be621be + e1fffd7
commit 83b702e
Show file tree

Hide file tree

Showing 7 changed files with 123 additions and 82 deletions.
diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml
@@ -54,8 +54,8 @@ body:
       description: How did you install HOOMD-blue?
       options:
         - Compiled from source
-        - Conda package
-        - glotzerlab-software container
+        - Conda-forge package
+        - glotzerlab-software package
     validations:
       required: true
   - type: input

diff --git a/BUILDING.rst b/BUILDING.rst
@@ -30,7 +30,7 @@ To build the documentation from source (optional):
 
 1. `Install prerequisites`_::
 
-   $ <package-manager> install sphinx furo nbsphinx ipython
+   $ <package-manager> install sphinx sphinx-copybutton furo nbsphinx ipython
 
 .. note::
 
@@ -86,7 +86,7 @@ Install prerequisites
 
 **For MPI parallel execution** (required when ``ENABLE_MPI=on``):
 
-- MPI (tested with OpenMPI, MVAPICH)
+- MPI (tested with OpenMPI)
 - cereal >= 1.1
 
 **For GPU execution** (required when ``ENABLE_GPU=on``):
@@ -109,9 +109,9 @@ Install prerequisites
 
   For **HOOMD-blue** on AMD GPUs, the following limitations currently apply.
 
-   1. Certain kernels trigger an `unknown HSA error <https://github.com/ROCm-Developer-Tools/HIP/issues/1662>`_.
-   2. The ``mpcd`` component is disabled on AMD GPUs.
-   3. Multi-GPU execution via unified memory is not available.
+  1. Certain kernels trigger an `unknown HSA error <https://github.com/ROCm-Developer-Tools/HIP/issues/1662>`_.
+  2. The ``mpcd`` component is disabled on AMD GPUs.
+  3. Multi-GPU execution via unified memory is not available.
 
 .. note::
 
@@ -130,6 +130,7 @@ Install prerequisites
 **To build the documentation:**
 
 - sphinx
+- sphinx-copybutton
 - furo
 - nbsphinx
 - ipython

diff --git a/INSTALLING.rst b/INSTALLING.rst
@@ -4,59 +4,52 @@
 Installing binaries
 ===================
 
-**HOOMD-blue** binaries are available in the glotzerlab-software_ Docker_/Singularity_ images and in
-packages on conda-forge_
+MPI parallel builds
+-------------------
 
-.. _glotzerlab-software: https://glotzerlab-software.readthedocs.io
-.. _Docker: https://hub.docker.com/
-.. _Singularity: https://www.sylabs.io/
-.. _conda-forge: https://conda-forge.org/docs/user/introduction.html
+You must build **HOOMD-blue** from source to enable support for the native **MPI** and **CUDA**
+libraries on your **HPC resource**. You can use the glotzerlab-software_ repository to manage such
+builds as conda packages.
 
-Singularity / Docker images
----------------------------
+.. _glotzerlab-software: https://glotzerlab-software.readthedocs.io
 
-See the glotzerlab-software_ documentation for instructions to install and use the containers on
-supported HPC clusters.
+Serial CPU and single GPU builds
+--------------------------------
 
-Conda package
--------------
+**HOOMD-blue** binaries for **serial CPU** and **single GPU** are available on conda-forge_ for the
+*linux-64*, *osx-64*, and *osx-arm64* platforms. Install the ``hoomd`` package from the conda-forge_
+channel into a conda environment::
 
-**HOOMD-blue** is available on conda-forge_ on the *linux-64*, *osx-64*, and *osx-arm64* platforms.
-Install the ``hoomd`` package from the conda-forge_ channel into a conda environment::
+    $ mamba install hoomd=4.7.0
 
-    $ conda install hoomd=4.7.0
+.. _conda-forge: https://conda-forge.org/docs/user/introduction.html
 
 ``conda`` auto-detects whether your system has a GPU and attempts to install the appropriate
 package. Override this and force the GPU enabled package installation with::
 
     $ export CONDA_OVERRIDE_CUDA="12.0"
-    $ conda install "hoomd=4.7.0=*gpu*" "cuda-version=12.0"
+    $ mamba install "hoomd=4.7.0=*gpu*" "cuda-version=12.0"
 
 Similarly, you can force CPU only package installation with::
 
-    $ conda install "hoomd=4.7.0=*cpu*"
+    $ mamba install "hoomd=4.7.0=*cpu*"
 
 .. note::
 
-    CUDA 11.2 compatible packages are also available. Replace "12.0" with "11.2" above when
+    CUDA 11.8 compatible packages are also available. Replace "12.0" with "11.8" above when
     installing HOOMD-blue on systems with CUDA 11 compatible drivers.
 
 .. note::
 
-    To use :ref:`run time compilation` on **macOS**, install the ``compilers`` package::
-
-        $ conda install compilers
-
-    Without this package you will get *file not found* errors when HOOMD-blue performs the run time
-    compilation.
+    Run time compilation is no longer available on conda-forge builds starting with HOOMD-blue
+    4.7.0.
 
 .. tip::
 
-    Use mambaforge_, miniforge_ or miniconda_ instead of the full Anaconda distribution to avoid
-    package conflicts with conda-forge_ packages. When using miniconda_, follow the instructions
-    provided in the conda-forge_ documentation to configure the channel selection so that all
-    packages are installed from the conda-forge_ channel.
+    Use miniforge_, miniconda_, or any other *minimal* conda environment provider instead of the
+    full Anaconda distribution to avoid package conflicts with conda-forge_ packages. When using
+    miniconda_, follow the instructions provided in the conda-forge_ documentation to configure the
+    channel selection so that all packages are installed from the conda-forge_ channel.
 
-.. _mambaforge: https://github.com/conda-forge/miniforge
 .. _miniforge: https://github.com/conda-forge/miniforge
 .. _miniconda: http://conda.pydata.org/miniconda.html
diff --git a/sphinx-doc/_templates/page.html b/sphinx-doc/_templates/page.html
@@ -1,49 +1,49 @@
 {% extends "furo/page.html" %}
 {% block footer %}
 <div class="related-pages">
-{% if next -%}
+  {% if next -%}
     <a class="next-page" href="{{ next.link }}">
-    <div class="page-info">
+      <div class="page-info">
         <div class="context">
-        <span>{{ _("Next") }}</span>
+          <span>{{ _("Next") }}</span>
         </div>
         <div class="title">{{ next.title }}</div>
-    </div>
-    <svg class="furo-related-icon"><use href="#svg-arrow-right"></use></svg>
+      </div>
+      <svg class="furo-related-icon"><use href="#svg-arrow-right"></use></svg>
     </a>
-{%- endif %}
-{% if prev -%}
+  {%- endif %}
+  {% if prev -%}
     <a class="prev-page" href="{{ prev.link }}">
-    <svg class="furo-related-icon"><use href="#svg-arrow-right"></use></svg>
-    <div class="page-info">
+      <svg class="furo-related-icon"><use href="#svg-arrow-right"></use></svg>
+      <div class="page-info">
         <div class="context">
-        <span>{{ _("Previous") }}</span>
+          <span>{{ _("Previous") }}</span>
         </div>
         {% if prev.link == pathto(master_doc) %}
         <div class="title">{{ _("Home") }}</div>
         {% else %}
         <div class="title">{{ prev.title }}</div>
         {% endif %}
-    </div>
+      </div>
     </a>
-{%- endif %}
+  {%- endif %}
 </div>
 <div class="bottom-of-page">
-<div class="left-details">
+  <div class="left-details">
     <p>Development of {{ project }} is led by the <a href="https://glotzerlab.engin.umich.edu">Glotzer Group</a> at the <a href="https://umich.edu">University of Michigan</a> (supported by NSF DMR 1808342) with many <a href="credits.html">external contributions</a>.
     </p>
 
     {%- if show_copyright %}
     <div class="copyright">
-    {%- if hasdoc('copyright') %}
+      {%- if hasdoc('copyright') %}
         {% trans path=pathto('copyright'), copyright=copyright|e -%}
-        <a href="{{ path }}">Copyright</a> &#169; {{ copyright }}
+          <a href="{{ path }}">Copyright</a> &#169; {{ copyright }}
         {%- endtrans %}
-    {%- else %}
+      {%- else %}
         {% trans copyright=copyright|e -%}
-        Copyright &#169; {{ copyright }}
+          Copyright &#169; {{ copyright }}
         {%- endtrans %}
-    {%- endif %}
+      {%- endif %}
     </div>
     {%- endif %}
     {% trans %}Made with {% endtrans -%}
@@ -56,16 +56,45 @@
     {% endtrans %}
     {%- if last_updated -%}
     <div class="last-updated">
-    {% trans last_updated=last_updated|e -%}
+      {% trans last_updated=last_updated|e -%}
         Last updated on {{ last_updated }}
-    {%- endtrans -%}
+      {%- endtrans -%}
     </div>
     {%- endif %}
-</div>
-<div class="right-details">
+  </div>
+  <div class="right-details">
     <a class="muted-link" href="http://umich.edu">
     <img src="{{ pathto('_static/umich-block-M.svg', 1) }}" alt="University of Michigan logo" style="width: 84px; float: right;" />
     </a>
-</div>
+
+    {% if theme_footer_icons or READTHEDOCS -%}
+    <div class="icons">
+      {% if theme_footer_icons -%}
+      {% for icon_dict in theme_footer_icons -%}
+      <a class="muted-link {{ icon_dict.class }}" href="{{ icon_dict.url }}" aria-label="{{ icon_dict.name }}">
+        {{- icon_dict.html -}}
+      </a>
+      {% endfor %}
+      {%- else -%}
+      {#- Show Read the Docs project -#}
+      {%- if READTHEDOCS and slug -%}
+      <a class="muted-link" href="https://readthedocs.org/projects/{{ slug }}" aria-label="On Read the Docs">
+        <svg x="0px" y="0px" viewBox="-125 217 360 360" xml:space="preserve">
+          <path fill="currentColor" d="M39.2,391.3c-4.2,0.6-7.1,4.4-6.5,8.5c0.4,3,2.6,5.5,5.5,6.3 c0,0,18.5,6.1,50,8.7c25.3,2.1,54-1.8,54-1.8c4.2-0.1,7.5-3.6,7.4-7.8c-0.1-4.2-3.6-7.5-7.8-7.4c-0.5,0-1,0.1-1.5,0.2 c0,0-28.1,3.5-50.9,1.6c-30.1-2.4-46.5-7.9-46.5-7.9C41.7,391.3,40.4,391.1,39.2,391.3z M39.2,353.6c-4.2,0.6-7.1,4.4-6.5,8.5 c0.4,3,2.6,5.5,5.5,6.3c0,0,18.5,6.1,50,8.7c25.3,2.1,54-1.8,54-1.8c4.2-0.1,7.5-3.6,7.4-7.8c-0.1-4.2-3.6-7.5-7.8-7.4 c-0.5,0-1,0.1-1.5,0.2c0,0-28.1,3.5-50.9,1.6c-30.1-2.4-46.5-7.9-46.5-7.9C41.7,353.6,40.4,353.4,39.2,353.6z M39.2,315.9 c-4.2,0.6-7.1,4.4-6.5,8.5c0.4,3,2.6,5.5,5.5,6.3c0,0,18.5,6.1,50,8.7c25.3,2.1,54-1.8,54-1.8c4.2-0.1,7.5-3.6,7.4-7.8 c-0.1-4.2-3.6-7.5-7.8-7.4c-0.5,0-1,0.1-1.5,0.2c0,0-28.1,3.5-50.9,1.6c-30.1-2.4-46.5-7.9-46.5-7.9 C41.7,315.9,40.4,315.8,39.2,315.9z M39.2,278.3c-4.2,0.6-7.1,4.4-6.5,8.5c0.4,3,2.6,5.5,5.5,6.3c0,0,18.5,6.1,50,8.7 c25.3,2.1,54-1.8,54-1.8c4.2-0.1,7.5-3.6,7.4-7.8c-0.1-4.2-3.6-7.5-7.8-7.4c-0.5,0-1,0.1-1.5,0.2c0,0-28.1,3.5-50.9,1.6 c-30.1-2.4-46.5-7.9-46.5-7.9C41.7,278.2,40.4,278.1,39.2,278.3z M-13.6,238.5c-39.6,0.3-54.3,12.5-54.3,12.5v295.7 c0,0,14.4-12.4,60.8-10.5s55.9,18.2,112.9,19.3s71.3-8.8,71.3-8.8l0.8-301.4c0,0-25.6,7.3-75.6,7.7c-49.9,0.4-61.9-12.7-107.7-14.2 C-8.2,238.6-10.9,238.5-13.6,238.5z M19.5,257.8c0,0,24,7.9,68.3,10.1c37.5,1.9,75-3.7,75-3.7v267.9c0,0-19,10-66.5,6.6 C59.5,536.1,19,522.1,19,522.1L19.5,257.8z M-3.6,264.8c4.2,0,7.7,3.4,7.7,7.7c0,4.2-3.4,7.7-7.7,7.7c0,0-12.4,0.1-20,0.8 c-12.7,1.3-21.4,5.9-21.4,5.9c-3.7,2-8.4,0.5-10.3-3.2c-2-3.7-0.5-8.4,3.2-10.3c0,0,0,0,0,0c0,0,11.3-6,27-7.5 C-16,264.9-3.6,264.8-3.6,264.8z M-11,302.6c4.2-0.1,7.4,0,7.4,0c4.2,0.5,7.2,4.3,6.7,8.5c-0.4,3.5-3.2,6.3-6.7,6.7 c0,0-12.4,0.1-20,0.8c-12.7,1.3-21.4,5.9-21.4,5.9c-3.7,2-8.4,0.5-10.3-3.2c-2-3.7-0.5-8.4,3.2-10.3c0,0,11.3-6,27-7.5 C-20.5,302.9-15.2,302.7-11,302.6z M-3.6,340.2c4.2,0,7.7,3.4,7.7,7.7s-3.4,7.7-7.7,7.7c0,0-12.4-0.1-20,0.7 c-12.7,1.3-21.4,5.9-21.4,5.9c-3.7,2-8.4,0.5-10.3-3.2c-2-3.7-0.5-8.4,3.2-10.3c0,0,11.3-6,27-7.5C-16,340.1-3.6,340.2-3.6,340.2z" />
+        </svg>
+      </a>
+      {%- endif -%}
+      {#- Show GitHub repository home -#}
+      {%- if READTHEDOCS and display_github and github_user != "None" and github_repo != "None" -%}
+      <a class="muted-link" href="https://github.com/{{ github_user }}/{{ github_repo }}" aria-label="On GitHub">
+        <svg stroke="currentColor" fill="currentColor" stroke-width="0" viewBox="0 0 16 16">
+          <path fill-rule="evenodd" d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0 0 16 8c0-4.42-3.58-8-8-8z"></path>
+        </svg>
+      </a>
+      {%- endif -%}
+      {%- endif %}
+    </div>
+    {%- endif %}
+  </div>
 </div>
 {% endblock footer %}
diff --git a/sphinx-doc/conf.py b/sphinx-doc/conf.py
@@ -27,9 +27,14 @@
 extensions = [
     'nbsphinx', 'sphinx.ext.autodoc', 'sphinx.ext.autosummary',
     'sphinx.ext.napoleon', 'sphinx.ext.intersphinx', 'sphinx.ext.mathjax',
-    'sphinx.ext.todo', 'IPython.sphinxext.ipython_console_highlighting'
+    'sphinx.ext.todo', 'IPython.sphinxext.ipython_console_highlighting',
+    'sphinx_copybutton'
 ]
 
+if os.getenv("READTHEDOCS"):
+    extensions.append("sphinxcontrib.googleanalytics")
+    googleanalytics_id = "G-ZR0DNZD21E"
+
 napoleon_include_special_with_doc = True
 
 intersphinx_mapping = {
@@ -80,7 +85,8 @@
 html_logo = 'hoomdblue-logo-vertical.svg'
 html_theme_options = {
     'sidebar_hide_name': True,
-    'top_of_page_button': None,
+    'top_of_page_buttons': [],
+    "navigation_with_keys": True,
     "dark_css_variables": {
         "color-brand-primary": "#5187b2",
         "color-brand-content": "#5187b2",
@@ -95,6 +101,10 @@
 IGNORE_MODULES = ['hoomd._hoomd']
 IGNORE_CLASSES = []
 
+copybutton_prompt_text = "$ "
+copybutton_remove_prompts = True
+copybutton_line_continuation_character = "\\"
+
 
 def autodoc_process_bases(app, name, obj, options, bases):
     """Ignore base classes from the '_hoomd' module."""

diff --git a/sphinx-doc/requirements.in b/sphinx-doc/requirements.in
@@ -1,8 +1,10 @@
 ipython==8.24.0
 nbconvert==7.16.4
-nbsphinx==0.9.3
+nbsphinx==0.9.4
 numpy==1.26.4
 pandoc==2.3
 sphinx==7.3.7
-furo==2024.4.27
+furo==2024.5.6
 tornado==6.4
+sphinxcontrib-googleanalytics==0.4
+sphinx-copybutton==0.5.2