Merge branch 'update-docs' into trunk-minor

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -55,8 +55,7 @@ body:
       description: How did you install GSD?
       options:
         - Compiled from source
-        - Conda package
-        - glotzerlab-software container
+        - Conda-forge package
         - PyPI package
     validations:
       required: true

.github/requirements-build-sdist.in

@@ -0,0 +1 @@
+build == 1.1.1

.github/requirements-build-sdist.txt

@@ -1 +1,12 @@
-build == 1.1.1
+#
+# This file is autogenerated by pip-compile with Python 3.12
+# by the following command:
+#
+#    pip-compile requirements-build-sdist.in
+#
+build==1.1.1
+    # via -r requirements-build-sdist.in
+packaging==24.0
+    # via build
+pyproject-hooks==1.1.0
+    # via build

.github/requirements-test.in

@@ -0,0 +1,3 @@
+cython == 3.0.8
+numpy == 1.26.4
+pytest == 8.2.0

.github/requirements-test.txt

@@ -1,3 +1,18 @@
-cython == 3.0.8
-numpy == 1.26.4
-pytest == 8.1.0
+#
+# This file is autogenerated by pip-compile with Python 3.12
+# by the following command:
+#
+#    pip-compile requirements-test.in
+#
+cython==3.0.8
+    # via -r requirements-test.in
+iniconfig==2.0.0
+    # via pytest
+numpy==1.26.4
+    # via -r requirements-test.in
+packaging==24.0
+    # via pytest
+pluggy==1.5.0
+    # via pytest
+pytest==8.2.0
+    # via -r requirements-test.in

.pre-commit-config.yaml

@@ -17,10 +17,11 @@ repos:
     args:
     - --remove
   - id: mixed-line-ending
-- repo: https://github.com/rhysd/actionlint
-  rev: v1.6.27
-  hooks:
-    - id: actionlint
+# actionlint fails to build on mac...
+# - repo: https://github.com/rhysd/actionlint
+#   rev: v1.6.27
+#   hooks:
+#     - id: actionlint
 - repo: https://github.com/glotzerlab/fix-license-header
   rev: v0.3.2
   hooks:

.readthedocs.yaml

@@ -4,6 +4,9 @@ build:
   os: ubuntu-22.04
   tools:
     python: "3.12"
+  jobs:
+    pre_build:
+    - doxygen
 
 sphinx:
   fail_on_warning: true

CHANGELOG.rst

@@ -10,6 +10,18 @@ Change Log
 3.x
 ---
 
+3.3.0 (not yet released)
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+*Changed:*
+
+* Navigate the documentation with arrow keys
+  (`#365 <https://github.com/glotzerlab/gsd/pull/365>`__).
+* Add button to copy code snippets from the documentation
+  (`#365 <https://github.com/glotzerlab/gsd/pull/365>`__).
+* Remove singularity reference from the documentation
+  (`#365 <https://github.com/glotzerlab/gsd/pull/365>`__).
+
 3.2.1 (2024-01-22)
 ^^^^^^^^^^^^^^^^^^
 

INSTALLING.rst

@@ -4,13 +4,9 @@
 Installation
 ============
 
-**gsd** binaries are available in the glotzerlab-software_ Docker_/Singularity_ images and in
-packages on conda-forge_ and PyPI_. You can also compile **gsd** from source, embed ``gsd.c`` in
-your code, or read gsd files with a pure Python reader ``pygsd.py``.
+**gsd** binaries are available on conda-forge_ and PyPI_. You can also compile **gsd** from source,
+embed ``gsd.c`` in your code, or read gsd files with a pure Python reader ``pygsd.py``.
 
-.. _glotzerlab-software: https://glotzerlab-software.readthedocs.io
-.. _Docker: https://hub.docker.com/
-.. _Singularity: https://www.sylabs.io/
 .. _conda-forge: https://conda-forge.org/
 .. _PyPI: https://pypi.org/
 
@@ -21,20 +17,21 @@ Conda package
 ^^^^^^^^^^^^^
 
 **gsd** is available on conda-forge_ on the *linux-64*, *linux-aarch64*, *linux-ppc64le*, *osx-64*,
-*osx-arm64* and *win-64* platforms. To install, download and install miniforge_ or miniconda_ Then
-install **gsd** from the conda-forge_ channel:
-
-.. _miniforge: https://github.com/conda-forge/miniforge
-.. _miniconda: http://conda.pydata.org/miniconda.html
+*osx-arm64* and *win-64* platforms.
 
 .. code-block:: bash
 
-   $ conda install -c conda-forge gsd
+   $ conda install gsd
 
-Singularity / Docker images
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+.. tip::
 
-See the glotzerlab-software_ documentation for instructions to install and use the containers.
+    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.
+
+.. _miniforge: https://github.com/conda-forge/miniforge
+.. _miniconda: http://conda.pydata.org/miniconda.html
 
 PyPI
 ^^^^
@@ -77,7 +74,7 @@ To build the documentation from source (optional):
 
 1. `Install prerequisites`_::
 
-   $ <package-manager> install breathe doxygen sphinx furo ipython
+   $ <package-manager> install breathe doxygen sphinx furo ipython sphinx-copybutton
 
 2. `Build the documentation`_::
 
@@ -121,9 +118,10 @@ Install prerequisites
 
 * **breathe**
 * **Doxygen**
-* **Sphinx**
-* **IPython**
 * **furo**
+* **IPython**
+* **Sphinx**
+* **sphinx-copybutton**
 * an internet connection
 
 **To execute unit tests:**

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>.
     </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 %}

doc/conf.py

@@ -4,7 +4,6 @@
 
 import datetime
 import os
-import subprocess
 import tempfile
 
 import gsd
@@ -17,8 +16,13 @@
     'sphinx.ext.mathjax',
     'IPython.sphinxext.ipython_console_highlighting',
     'IPython.sphinxext.ipython_directive',
+    'sphinx_copybutton',
 ]
 
+if os.getenv('READTHEDOCS'):
+    extensions.append('sphinxcontrib.googleanalytics')
+    googleanalytics_id = 'G-25TF48HJ76'
+
 napoleon_include_special_with_doc = True
 
 intersphinx_mapping = {
@@ -51,6 +55,8 @@
 html_theme = 'furo'
 html_static_path = ['_static']
 html_theme_options = {
+    'navigation_with_keys': True,
+    'top_of_page_buttons': [],
     'dark_css_variables': {
         'color-brand-primary': '#5187b2',
         'color-brand-content': '#5187b2',
@@ -61,6 +67,11 @@
     },
 }
 
+copybutton_prompt_text = r'>>> |\.\.\. |\$ |In \[\d*\]: | {2,5}\.\.\.: | {5,8}: '
+copybutton_prompt_is_regexp = True
+copybutton_remove_prompts = True
+copybutton_line_continuation_character = '\\'
+
 
 ### Add custom directives
 def setup(app):
@@ -90,8 +101,3 @@ def setup(app):
 breathe_domain_by_extension = {
     'h': 'c',
 }
-
-read_the_docs_build = os.environ.get('READTHEDOCS', None) == 'True'
-
-if read_the_docs_build:
-    subprocess.call('cd ..; doxygen', shell=True)

doc/requirements.in

@@ -1,8 +1,10 @@
 breathe == 4.35.0
 cython == 3.0.10
-furo == 2024.4.27
+furo == 2024.5.6
 ipython == 8.24.0
 numpy == 1.26.4
 pandas == 2.2.2
 pyarrow == 16.0.0
 sphinx == 7.3.7
+sphinxcontrib-googleanalytics==0.4
+sphinx-copybutton==0.5.2