diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml index df966af5..d4b8510d 100644 --- a/.github/ISSUE_TEMPLATE/bug_report.yml +++ b/.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 diff --git a/.github/requirements-build-sdist.in b/.github/requirements-build-sdist.in new file mode 100644 index 00000000..f9a78070 --- /dev/null +++ b/.github/requirements-build-sdist.in @@ -0,0 +1 @@ +build == 1.1.1 diff --git a/.github/requirements-build-sdist.txt b/.github/requirements-build-sdist.txt index f9a78070..d348edf8 100644 --- a/.github/requirements-build-sdist.txt +++ b/.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 diff --git a/.github/requirements-test.in b/.github/requirements-test.in new file mode 100644 index 00000000..d1320662 --- /dev/null +++ b/.github/requirements-test.in @@ -0,0 +1,3 @@ +cython == 3.0.8 +numpy == 1.26.4 +pytest == 8.2.0 diff --git a/.github/requirements-test.txt b/.github/requirements-test.txt index 2335e31f..71ec678a 100644 --- a/.github/requirements-test.txt +++ b/.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 diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index 67d86bf7..f75a5226 100644 --- a/.pre-commit-config.yaml +++ b/.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: diff --git a/.readthedocs.yaml b/.readthedocs.yaml index 98738254..6746983d 100644 --- a/.readthedocs.yaml +++ b/.readthedocs.yaml @@ -4,6 +4,9 @@ build: os: ubuntu-22.04 tools: python: "3.12" + jobs: + pre_build: + - doxygen sphinx: fail_on_warning: true diff --git a/CHANGELOG.rst b/CHANGELOG.rst index ca651e06..7d181ae5 100644 --- a/CHANGELOG.rst +++ b/CHANGELOG.rst @@ -10,6 +10,18 @@ Change Log 3.x --- +3.3.0 (not yet released) +^^^^^^^^^^^^^^^^^^^^^^^^ + +*Changed:* + +* Navigate the documentation with arrow keys + (`#365 `__). +* Add button to copy code snippets from the documentation + (`#365 `__). +* Remove singularity reference from the documentation + (`#365 `__). + 3.2.1 (2024-01-22) ^^^^^^^^^^^^^^^^^^ diff --git a/INSTALLING.rst b/INSTALLING.rst index 2fb37839..e6b3c937 100644 --- a/INSTALLING.rst +++ b/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`_:: - $ install breathe doxygen sphinx furo ipython + $ 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:** diff --git a/doc/_templates/page.html b/doc/_templates/page.html index e284003a..d6e2e8bf 100644 --- a/doc/_templates/page.html +++ b/doc/_templates/page.html @@ -1,49 +1,49 @@ {% extends "furo/page.html" %} {% block footer %}
-{% if next -%} + {% if next -%} -
+
- {{ _("Next") }} + {{ _("Next") }}
{{ next.title }}
-
- +
+ -{%- endif %} -{% if prev -%} + {%- endif %} + {% if prev -%} - -
+ +
- {{ _("Previous") }} + {{ _("Previous") }}
{% if prev.link == pathto(master_doc) %}
{{ _("Home") }}
{% else %}
{{ prev.title }}
{% endif %} -
+
-{%- endif %} + {%- endif %}
-
+

Development of {{ project }} is led by the Glotzer Group at the University of Michigan.

{%- if show_copyright %}
- {%- if hasdoc('copyright') %} + {%- if hasdoc('copyright') %} {% trans path=pathto('copyright'), copyright=copyright|e -%} - Copyright © {{ copyright }} + Copyright © {{ copyright }} {%- endtrans %} - {%- else %} + {%- else %} {% trans copyright=copyright|e -%} - Copyright © {{ copyright }} + Copyright © {{ copyright }} {%- endtrans %} - {%- endif %} + {%- endif %}
{%- endif %} {% trans %}Made with {% endtrans -%} @@ -56,16 +56,45 @@ {% endtrans %} {%- if last_updated -%}
- {% trans last_updated=last_updated|e -%} + {% trans last_updated=last_updated|e -%} Last updated on {{ last_updated }} - {%- endtrans -%} + {%- endtrans -%}
{%- endif %} -
-
+
+
University of Michigan logo -
+ + {% if theme_footer_icons or READTHEDOCS -%} +
+ {% if theme_footer_icons -%} + {% for icon_dict in theme_footer_icons -%} + + {{- icon_dict.html -}} + + {% endfor %} + {%- else -%} + {#- Show Read the Docs project -#} + {%- if READTHEDOCS and slug -%} + + + + + + {%- endif -%} + {#- Show GitHub repository home -#} + {%- if READTHEDOCS and display_github and github_user != "None" and github_repo != "None" -%} + + + + + + {%- endif -%} + {%- endif %} +
+ {%- endif %} +
{% endblock footer %} diff --git a/doc/conf.py b/doc/conf.py index 367d54f1..7b54ef9d 100644 --- a/doc/conf.py +++ b/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) diff --git a/doc/requirements.in b/doc/requirements.in index 6119a51f..faf81890 100644 --- a/doc/requirements.in +++ b/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 diff --git a/doc/requirements.txt b/doc/requirements.txt index b0def29c..3bca3f02 100644 --- a/doc/requirements.txt +++ b/doc/requirements.txt @@ -2,7 +2,7 @@ # This file is autogenerated by pip-compile with Python 3.12 # by the following command: # -# pip-compile requirements.in +# pip-compile doc/requirements.in # alabaster==0.7.16 # via sphinx @@ -13,13 +13,13 @@ babel==2.14.0 beautifulsoup4==4.12.3 # via furo breathe==4.35.0 - # via -r requirements.in + # via -r doc/requirements.in certifi==2024.2.2 # via requests charset-normalizer==3.3.2 # via requests cython==3.0.10 - # via -r requirements.in + # via -r doc/requirements.in decorator==5.1.1 # via ipython docutils==0.21.2 @@ -28,14 +28,14 @@ docutils==0.21.2 # sphinx executing==2.0.1 # via stack-data -furo==2024.4.27 - # via -r requirements.in +furo==2024.5.6 + # via -r doc/requirements.in idna==3.7 # via requests imagesize==1.4.1 # via sphinx ipython==8.24.0 - # via -r requirements.in + # via -r doc/requirements.in jedi==0.19.1 # via ipython jinja2==3.1.4 @@ -46,13 +46,13 @@ matplotlib-inline==0.1.7 # via ipython numpy==1.26.4 # via - # -r requirements.in + # -r doc/requirements.in # pandas # pyarrow packaging==24.0 # via sphinx pandas==2.2.2 - # via -r requirements.in + # via -r doc/requirements.in parso==0.8.4 # via jedi pexpect==4.9.0 @@ -64,7 +64,7 @@ ptyprocess==0.7.0 pure-eval==0.2.2 # via stack-data pyarrow==16.0.0 - # via -r requirements.in + # via -r doc/requirements.in pygments==2.17.2 # via # furo @@ -86,16 +86,22 @@ soupsieve==2.5 # via beautifulsoup4 sphinx==7.3.7 # via - # -r requirements.in + # -r doc/requirements.in # breathe # furo # sphinx-basic-ng + # sphinx-copybutton + # sphinxcontrib-googleanalytics sphinx-basic-ng==1.0.0b2 # via furo +sphinx-copybutton==0.5.2 + # via -r doc/requirements.in sphinxcontrib-applehelp==1.0.8 # via sphinx sphinxcontrib-devhelp==1.0.6 # via sphinx +sphinxcontrib-googleanalytics==0.4 + # via -r doc/requirements.in sphinxcontrib-htmlhelp==2.0.5 # via sphinx sphinxcontrib-jsmath==1.0.1