Merge pull request #293 from boutproject/fix-rtd-config

Fix lots of docs issues, autogen API, switch theme

.gitignore

@@ -68,6 +68,7 @@ instance/
 
 # Sphinx documentation
 docs/_build/
+docs/generated
 
 # PyBuilder
 target/

.readthedocs.yml

@@ -1,8 +1,28 @@
+# Read the Docs configuration file for Sphinx projects
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+
+# Set the OS, Python version and other tools you might need
 build:
-  image: latest
+  os: ubuntu-22.04
+  tools:
+    python: "3.11"
+
+# Build documentation in the "docs/" directory with Sphinx
+sphinx:
+  configuration: docs/conf.py
+
+# Optionally build your docs in additional formats such as PDF and ePub
+# formats:
+#    - pdf
+#    - epub
 
+# See https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html
 python:
-  version: 3.8
-  pip_install: true
-  extra_requirements:
-    - docs
+   install:
+   - method: pip
+     path: .
+     extra_requirements:
+       - docs

docs/_templates/custom-class-template.rst

@@ -0,0 +1,32 @@
+{{ fullname | escape | underline}}
+
+.. currentmodule:: {{ module }}
+
+.. autoclass:: {{ objname }}
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+   {% block methods %}
+   .. automethod:: __init__
+
+   {% if methods %}
+   .. rubric:: {{ _('Methods') }}
+
+   .. autosummary::
+   {% for item in methods %}
+      ~{{ name }}.{{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+   {% block attributes %}
+   {% if attributes %}
+   .. rubric:: {{ _('Attributes') }}
+
+   .. autosummary::
+   {% for item in attributes %}
+      ~{{ name }}.{{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}

docs/_templates/custom-module-template.rst

@@ -0,0 +1,66 @@
+{{ fullname | escape | underline}}
+
+.. automodule:: {{ fullname }}
+
+   {% block attributes %}
+   {% if attributes %}
+   .. rubric:: {{ _('Module Attributes') }}
+
+   .. autosummary::
+      :toctree:
+   {% for item in attributes %}
+      {{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+   {% block functions %}
+   {% if functions %}
+   .. rubric:: {{ _('Functions') }}
+
+   .. autosummary::
+      :toctree:
+   {% for item in functions %}
+      {{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+   {% block classes %}
+   {% if classes %}
+   .. rubric:: {{ _('Classes') }}
+
+   .. autosummary::
+      :toctree:
+      :template: custom-class-template.rst
+   {% for item in classes %}
+      {{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+   {% block exceptions %}
+   {% if exceptions %}
+   .. rubric:: {{ _('Exceptions') }}
+
+   .. autosummary::
+      :toctree:
+   {% for item in exceptions %}
+      {{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+{% block modules %}
+{% if modules %}
+.. rubric:: Modules
+
+.. autosummary::
+   :toctree:
+   :template: custom-module-template.rst
+   :recursive:
+{% for item in modules %}
+   {{ item }}
+{%- endfor %}
+{% endif %}
+{% endblock %}

docs/accessor_methods.rst

@@ -1,8 +1,8 @@
 BoutDataset Accessor Methods
 ============================
 
-xBOUT defines a set of accessor_ methods on the loaded Datasets and
-DataArrays, which are called by `ds.bout.method`.
+xBOUT defines a set of accessor_ methods on the loaded `xarray.Dataset` and
+`xarray.DataArray`, which are called by ``ds.bout.<method>``.
 
 This is where BOUT-specific data manipulation, analysis and plotting
 functionality is stored, for example::
@@ -17,4 +17,7 @@ or::
 
   ds.bout.create_restarts(savepath='.', nxpe=4, nype=4)
 
-.. _accessor: https://xarray.pydata.org/en/stable/internals.html#extending-xarray
+See `BoutDatasetAccessor` and `BoutDataArrayAccessor` for details on
+the available methods.
+
+.. _accessor: https://docs.xarray.dev/en/stable/internals/extending-xarray.html

docs/api.rst

@@ -0,0 +1,10 @@
+===============
+ API Reference
+===============
+
+.. autosummary::
+   :toctree: generated
+   :template: custom-module-template.rst
+   :recursive:
+
+   xbout

docs/conf.py

@@ -12,27 +12,19 @@
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
 #
-import os
 
-# import sys
-# sys.path.insert(0, os.path.abspath('.'))
-
-# Are we running on readthedocs?
-on_rtd = os.environ.get("READTHEDOCS") == "True"
+from importlib.metadata import version as get_version
 
 # -- Project information -----------------------------------------------------
 
-import xbout
-
 project = "xBOUT"
-copyright = "2018, Tom Nicholas"
+copyright = "2018-2023, Tom Nicholas, BOUT++ team"
 author = "Tom Nicholas"
 
-# The short X.Y version
-version = xbout.__version__
 # The full version, including alpha/beta/rc tags
-release = xbout.__version__
-
+release = get_version("xbout")
+# The short X.Y version
+version = ".".join(release.split(".")[:2])
 
 # -- General configuration ---------------------------------------------------
 
@@ -45,12 +37,26 @@
 # ones.
 extensions = [
     "sphinx.ext.autodoc",
+    "sphinx.ext.autosummary",
     "sphinx.ext.coverage",
     "sphinx.ext.mathjax",
     "sphinx.ext.viewcode",
     "sphinx.ext.napoleon",
+    "sphinx.ext.intersphinx",
+    "sphinx_autodoc_typehints",
 ]
 
+autosummary_generate = True
+autodoc_default_options = {"ignore-module-all": True}
+autodoc_typehints = "description"
+autodoc_class_signature = "mixed"
+
+# Numpy-doc config
+napoleon_google_docstring = False
+napoleon_numpy_docstring = True
+napoleon_attr_annotations = True
+napoleon_preprocess_types = True
+
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ["_templates"]
 
@@ -68,7 +74,7 @@
 #
 # This is also used if you do content translation via gettext catalogs.
 # Usually you set "language" from the command line for these cases.
-language = None
+language = "en"
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
@@ -85,21 +91,26 @@
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 #
-if on_rtd:
-    html_theme = "default"
-else:
-    html_theme = "alabaster"
+html_theme = "sphinx_book_theme"
 
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the
 # documentation.
 #
-# html_theme_options = {}
+html_theme_options = {
+    "repository_url": "https://github.com/boutproject/xBOUT",
+    "repository_branch": "master",
+    "path_to_docs": "docs",
+    "use_edit_page_button": True,
+    "use_repository_button": True,
+    "use_issues_button": True,
+    "home_page_in_toc": False,
+}
 
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
-html_static_path = ["_static"]
+html_static_path = ["images"]
 
 # Custom sidebar templates, must be a dictionary that maps document names
 # to template names.
@@ -169,3 +180,11 @@
 
 
 # -- Extension configuration -------------------------------------------------
+
+intersphinx_mapping = {
+    "python": ("https://docs.python.org/3", None),
+    "numpy": ("https://numpy.org/doc/stable", None),
+    "scipy": ("https://docs.scipy.org/doc/scipy", None),
+    "xarray": ("https://docs.xarray.dev/en/latest", None),
+    "mayavi": ("https://docs.enthought.com/mayavi/mayavi/", None),
+}

docs/extending_xbout.rst

@@ -3,12 +3,12 @@ Extending xBOUT for your BOUT module
 
 The accessor classes `BoutDatasetAccessor` and `BoutDataArrayAccessor`
 are intended to be subclassed for specific BOUT++ modules. The
-subclass accessor will then inherit all the `.bout` accessor methods,
+subclass accessor will then inherit all the ``.bout`` accessor methods,
 but you will also be able to override these and define your own
 methods within your new accessor.
 
 
-For example to add an extra method specific to the `STORM` BOUT++
+For example to add an extra method specific to the ``STORM`` BOUT++
 module::
 
   from xarray import register_dataset_accessor
@@ -26,7 +26,7 @@ module::
   >>> ds.storm.special_method()
   Do something only STORM users would want to do
 
-There is included an example of a `StormDataset` which contains all
+There is included an example of a ``StormDataset`` which contains all
 the data from a STORM_ simulation, as well as extra calculated
 quantities which are specific to the STORM module.
 

docs/index.rst

@@ -22,24 +22,29 @@ suggestions.
    loading_data
    accessor_methods
    extending_xbout
-   xbout
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Reference
+
+   API Reference <api>
 
 Installation
 ------------
 
-With `pip`:
+With ``pip``:
 
 .. code-block:: bash
 
   pip install --user xbout
 
-or `conda`:
+or ``conda``:
 
 .. code-block:: bash
 
   conda install -c conda-forge xbout
 
-You can run the tests by running `pytest --pyargs xbout`.
+You can run the tests by running ``pytest --pyargs xbout``.
 
 xBOUT will install the required python packages when you run one of
 the above install commands if they are not already installed on your

docs/loading_data.rst

@@ -10,6 +10,6 @@ The data from a BOUT++ run can be loaded with just::
   bd = open_boutdataset('./run_dir*/BOUT.dmp.*.nc', inputfilepath='./BOUT.inp')
 
 `open_boutdataset` returns an instance of an `xarray.Dataset` which
-contains BOUT-specific information in the `attrs`, so represents a
+contains BOUT-specific information in the ``attrs``, so represents a
 general structure for storing all of the output of a simulation,
 including data, input options and (soon) grid data.