Expand the documentation setup (#40)

* Add a file for hyperlinks

* Add a file for reST substitutions

* Update documentation configuration file

* Use pre-commit to reformat a subset of files

* Reformat some more files

* Add sphinx_automodapi.automodapi

* Add blank bibliography

* Use reST links in index.rst

* Add link for XRT

* Docstrings for modules

* Add api_static page for xrtpy.response.channel.rst

* Add back api_static pages

* Add docstring for resolve_filter_name

* Add bib entries

* Add rst_epilog & stop using graphviz

* Add an empty glossary

* Start a getting started page

* Update index page

* Add module docstrings and update imports

* Add docs/api to gitignore

* Adapt units notebook from PlasmaPy

* Add notebook gallery to getting started page

* Add examples page

* Expand main table of contents for docs

* Add ipykernel to docs requirements

* Add back graphviz

* Use nitpicky option for build_docs tox environment

* Ignore genx & geny files

* Remove some exclude_patterns

* Add ipython to requirements for doc builds

* Add css files from PlasmaPy

* Add css files

* Update tox.ini

* Add installation instructions adapted from PlasmaPy

* Add |minpython| to _substitutions.rst

* Add a bunch of links likely to be used

* Add a bunch of reST substitutions likely to be used

* Add some reST workarounds that we might or might not use

* Update installation instructions

* Run pre-commit on docs files

* Change the html anchors for references

...to make them more persistent than ``id20``, etc.

* Create mostly blank pages for contributor guide

* Remove docs/requirements.txt

* Update formats for readthedocs

* Add index page for response narrative docs

* Apply pre-commit format fixes

* Add a link to Python

* Update readthedocs config file

* Rename RTD config file extension

* Update RTD config

* Update RTD config

* Update RTD config

* Remove some RTD settings

* Update docs testing environments

* Rename variable

* Go back to PlasmaPy's rtd config

* Try newer Python version for rtd

* Downgrade version of Python for rtd

newer versions aren't supported yet

* Remove broken link

* Update installation instructions

.github/workflows/stale.yml

@@ -1,18 +1,18 @@
-name: 'Close stale issues and PR'
+name: Close stale issues and PR
 on:
   schedule:
-    - cron: '30 1 * * *'
+  - cron: 30 1 * * *
 
 jobs:
   stale:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/stale@v3
-        with:
-          repo-token: ${{ secrets.GITHUB_TOKEN }}
-          stale-pr-message: 'This pull request will be closed in 14 days due to six months of inactivity unless the stale label or comment is removed.'
-          close-pr-message: 'This pull request was closed because it has had no activity for the past six months.'
-          days-before-pr-stale: 180
-          days-before-pr-close: 15
+    - uses: actions/stale@v3
+      with:
+        repo-token: ${{ secrets.GITHUB_TOKEN }}
+        stale-pr-message: This pull request will be closed in 14 days due to six months of inactivity unless the stale label or comment is removed.
+        close-pr-message: This pull request was closed because it has had no activity for the past six months.
+        days-before-pr-stale: 180
+        days-before-pr-close: 15
           # never close issues
-          days-before-close: -1
+        days-before-close: -1

.github/workflows/testing.yml

@@ -117,7 +117,7 @@ jobs:
     - name: Install language-pack-fr and tzdata
       run: sudo apt-get install graphviz pandoc
     - name: Build documentation
-      run: tox -e build_docs_nitpicky -- -q
+      run: tox -e build_docs -- -q
   codespell:
     name: codespell
     runs-on: ubuntu-latest

.gitignore

@@ -70,6 +70,7 @@ instance/
 
 # Sphinx documentation
 docs/_build/
+docs/api
 
 # PyBuilder
 target/

.readthedocs.yaml

@@ -0,0 +1,13 @@
+version: 2
+
+formats:
+- htmlzip
+
+python:
+  version: '3.8'
+  install:
+  - requirements: requirements/install.txt
+  - requirements: requirements/docs.txt
+  - method: setuptools
+    path: .
+  system_packages: true

docs/_links.rst

@@ -0,0 +1,25 @@
+.. _Astropy: https://www.astropy.org
+.. _BibTeX format: https://www.bibtex.com/g/bibtex-format
+.. _BibTeX: http://www.bibtex.org
+.. _conda: https://docs.conda.io
+.. _git: https://git-scm.com
+.. _Hinode: https://www.nasa.gov/mission_pages/hinode/index.html
+.. _Jupyter: https://jupyter.org
+.. _matplotlib: https://matplotlib.org
+.. _NumPy: https://numpy.org
+.. _pip: https://pip.pypa.io
+.. _pre-commit: https://pre-commit.com
+.. _PyPI: https://pypi.org
+.. _pytest: https://docs.pytest.org
+.. _Python: https://www.python.org
+.. _Read the Docs: https://readthedocs.org
+.. _SciPy: https://scipy.org
+.. _SolarSoft IDL: https://www.lmsal.com/solarsoft
+.. _Sphinx: https://www.sphinx-doc.org
+.. _SunPy: https://docs.sunpy.org/en/stable
+.. _tox: https://tox.wiki/en/latest
+.. _X-Ray Telescope: https://xrt.cfa.harvard.edu
+.. _XRT: https://xrt.cfa.harvard.edu/
+.. _XRTpy's documentation: https://xrtpy.readthedocs.io/en/latest
+.. _XRTpy's GitHub repository: https://github.com/HinodeXRT/xrtpy
+.. _Zenodo: https://zenodo.org

docs/_static/css/admonition_color_contrast.css

@@ -0,0 +1,144 @@
+/*
+  The following sections were adapted from the file
+  sphinx_rtd_theme_ext_color_contrast/_static/sphinx_rtd_theme_ext_color_contrast.css
+  in the following repository:
+  https://github.com/AaltoSciComp/sphinx_rtd_theme_ext_color_contrast
+  The license is in our licenses directory.
+
+  These customizations will be able to be removed if sphinx_rtd_theme
+  defaults end up getting changed to meet accessibility guidelines.
+*/
+
+
+/* warning */
+.wy-alert.wy-alert-warning .wy-alert-title,
+.rst-content .wy-alert-warning.note .wy-alert-title,
+.rst-content .attention .wy-alert-title,
+.rst-content .caution .wy-alert-title,
+.rst-content .wy-alert-warning.danger .wy-alert-title,
+.rst-content .wy-alert-warning.error .wy-alert-title,
+.rst-content .wy-alert-warning.hint .wy-alert-title,
+.rst-content .wy-alert-warning.important .wy-alert-title,
+.rst-content .wy-alert-warning.tip .wy-alert-title,
+.rst-content .warning .wy-alert-title,
+.rst-content .wy-alert-warning.seealso .wy-alert-title,
+.rst-content .admonition-todo .wy-alert-title,
+.rst-content .wy-alert-warning.admonition .wy-alert-title,
+.wy-alert.wy-alert-warning .rst-content .admonition-title,
+.rst-content .wy-alert.wy-alert-warning .admonition-title,
+.rst-content .wy-alert-warning.note .admonition-title,
+.rst-content .attention .admonition-title,
+.rst-content .caution .admonition-title,
+.rst-content .wy-alert-warning.danger .admonition-title,
+.rst-content .wy-alert-warning.error .admonition-title,
+.rst-content .wy-alert-warning.hint .admonition-title,
+.rst-content .wy-alert-warning.important .admonition-title,
+.rst-content .wy-alert-warning.tip .admonition-title,
+.rst-content .warning .admonition-title, .rst-content
+.wy-alert-warning.seealso .admonition-title,
+.rst-content .admonition-todo .admonition-title,
+.rst-content .wy-alert-warning.admonition .admonition-title {
+    background: #B15E16;
+}
+
+/* important */
+
+.wy-alert.wy-alert-success .wy-alert-title,
+.rst-content .wy-alert-success.note .wy-alert-title,
+.rst-content .wy-alert-success.attention .wy-alert-title,
+.rst-content .wy-alert-success.caution .wy-alert-title,
+.rst-content .wy-alert-success.danger .wy-alert-title,
+.rst-content .wy-alert-success.error .wy-alert-title,
+.rst-content .hint .wy-alert-title,
+.rst-content .important .wy-alert-title,
+.rst-content .tip .wy-alert-title,
+.rst-content .wy-alert-success.warning .wy-alert-title,
+.rst-content .wy-alert-success.seealso .wy-alert-title,
+.rst-content .wy-alert-success.admonition-todo .wy-alert-title,
+.rst-content .wy-alert-success.admonition .wy-alert-title,
+.wy-alert.wy-alert-success .rst-content .admonition-title,
+.rst-content .wy-alert.wy-alert-success .admonition-title,
+.rst-content .wy-alert-success.note .admonition-title,
+.rst-content .wy-alert-success.attention .admonition-title,
+.rst-content .wy-alert-success.caution .admonition-title,
+.rst-content .wy-alert-success.danger .admonition-title,
+.rst-content .wy-alert-success.error .admonition-title,
+.rst-content .hint .admonition-title,
+.rst-content .important .admonition-title,
+.rst-content .tip .admonition-title,
+.rst-content .wy-alert-success.warning .admonition-title,
+.rst-content .wy-alert-success.seealso .admonition-title,
+.rst-content .wy-alert-success.admonition-todo .admonition-title,
+.rst-content .wy-alert-success.admonition .admonition-title {
+    background: #12826C;
+}
+
+/* seealso, note, etc */
+
+.wy-alert.wy-alert-info .wy-alert-title,
+.rst-content .note .wy-alert-title,
+.rst-content .wy-alert-info.attention .wy-alert-title,
+.rst-content .wy-alert-info.caution .wy-alert-title,
+.rst-content .wy-alert-info.danger .wy-alert-title,
+.rst-content .wy-alert-info.error .wy-alert-title,
+.rst-content .wy-alert-info.hint .wy-alert-title,
+.rst-content .wy-alert-info.important .wy-alert-title,
+.rst-content .wy-alert-info.tip .wy-alert-title,
+.rst-content .wy-alert-info.warning .wy-alert-title,
+.rst-content .seealso .wy-alert-title,
+.rst-content .wy-alert-info.admonition-todo .wy-alert-title,
+.rst-content .wy-alert-info.admonition .wy-alert-title,
+.wy-alert.wy-alert-info .rst-content .admonition-title,
+.rst-content .wy-alert.wy-alert-info .admonition-title,
+.rst-content .note .admonition-title,
+.rst-content .wy-alert-info.attention .admonition-title,
+.rst-content .wy-alert-info.caution .admonition-title,
+.rst-content .wy-alert-info.danger .admonition-title,
+.rst-content .wy-alert-info.error .admonition-title,
+.rst-content .wy-alert-info.hint .admonition-title,
+.rst-content .wy-alert-info.important .admonition-title,
+.rst-content .wy-alert-info.tip .admonition-title,
+.rst-content .wy-alert-info.warning .admonition-title,
+.rst-content .seealso .admonition-title,
+.rst-content .wy-alert-info.admonition-todo .admonition-title,
+.rst-content .wy-alert-info.admonition .admonition-title {
+    background: #277CB4;
+}
+
+/* error, danger */
+
+.rst-content .danger .admonition-title,
+.rst-content .danger .wy-alert-title,
+.rst-content .error .admonition-title,
+.rst-content .error .wy-alert-title,
+.rst-content .wy-alert-danger.admonition-todo .admonition-title,
+.rst-content .wy-alert-danger.admonition-todo .wy-alert-title,
+.rst-content .wy-alert-danger.admonition .admonition-title,
+.rst-content .wy-alert-danger.admonition .wy-alert-title,
+.rst-content .wy-alert-danger.attention .admonition-title,
+.rst-content .wy-alert-danger.attention .wy-alert-title,
+.rst-content .wy-alert-danger.caution .admonition-title,
+.rst-content .wy-alert-danger.caution .wy-alert-title,
+.rst-content .wy-alert-danger.hint .admonition-title,
+.rst-content .wy-alert-danger.hint .wy-alert-title,
+.rst-content .wy-alert-danger.important .admonition-title,
+.rst-content .wy-alert-danger.important .wy-alert-title,
+.rst-content .wy-alert-danger.note .admonition-title,
+.rst-content .wy-alert-danger.note .wy-alert-title,
+.rst-content .wy-alert-danger.seealso .admonition-title,
+.rst-content .wy-alert-danger.seealso .wy-alert-title,
+.rst-content .wy-alert-danger.tip .admonition-title,
+.rst-content .wy-alert-danger.tip .wy-alert-title,
+.rst-content .wy-alert-danger.warning .admonition-title,
+.rst-content .wy-alert-danger.warning .wy-alert-title,
+.rst-content .wy-alert.wy-alert-danger .admonition-title,
+.wy-alert.wy-alert-danger .rst-content .admonition-title,
+.wy-alert.wy-alert-danger .wy-alert-title {
+    background: #e31704;
+}
+
+/* Generic admonition titles */
+
+.wy-alert-title, .rst-content .admonition-title {
+    background: #277CB4;
+}