Various documentation improvements

docs/source/appctx.rst

@@ -5,8 +5,8 @@ The PETSc options provide a simple but powerful DSL for configuring composable s
 However, their main limitation is that the values of each option is limited to primitive C types, e.g. ``str``, ``float``, ``int``, or ``complex``.
 Sometimes more advanced data is useful or essential for building a particular solver.
 
-:class:`petsctools.Options <.options.Options>` fulfils this need by providing a means of passing arbitrary Python types through to Python PETSc types (e.g. Python type PCs).
-In this demo we show how to use the :class:`~.options.Options` to pass data to a custom Python type PC using the variable coefficient diffusion equation as an example.
+:class:`petsctools.Options` fulfils this need by providing a means of passing arbitrary Python types through to Python PETSc types (e.g. Python type PCs).
+In this demo we show how to use the :class:`petsctools.Options` to pass data to a custom Python type PC using the variable coefficient diffusion equation as an example.
 
 
 Diffusion equation with variable coefficients
@@ -61,10 +61,10 @@ Constructing :math:`P` requires two values, :math:`\sigma_{p}` and :math:`\omega
 
 2. The diffusion coefficient at each grid point :math:`\sigma_{p}(x_{i})` is defined as a numpy array.
    This is clearly not a primitive type and so cannot be passed via the :class:`PETSc.Options <petsc4py.PETSc.Options>` directly.
-   Instead, we access it via the :class:`~.options.Options` using the ``"djacobi_sigma"`` key.
+   Instead, we access it via the :class:`petsctools.Options` using the ``"djacobi_sigma"`` key.
 
-The :class:`~petsctools.options.Options` extends the :class:`PETSc.Options <petsc4py.PETSc.Options>` to permit containing arbitrary Python data.
-We will see below how to add ``sigma`` into the :class:`~petsctools.options.Options` so that it is available to the ``DiffusionJacobiPC``.
+The :class:`petsctools.Options` extends the :class:`PETSc.Options <petsc4py.PETSc.Options>` to permit containing arbitrary Python data.
+We will see below how to add ``sigma`` into the :class:`petsctools.Options` so that it is available to the ``DiffusionJacobiPC``.
 
 .. literalinclude:: ../../tests/docs/test_appctx_docs.py
     :language: python3
@@ -87,8 +87,8 @@ Assuming that :math:`\sigma'` is the component that may vary from solve to solve
 The Options and the AppContext
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Now we configure ``ksp`` by passing PETSc options as key-value pairs in the ``parameters`` dictionary to :func:`petsctools.set_from_options <.options.set_from_options>`.
-This function will create a :class:`petsctools.OptionsManager <.options.OptionsManager>` and attach it to ``ksp``.
+Now we configure ``ksp`` by passing PETSc options as key-value pairs in the ``parameters`` dictionary to :func:`petsctools.set_from_options`.
+This function will create a :class:`petsctools.OptionsManager` and attach it to ``ksp``.
 Observe that we are passing arbitrary Python data (``sigma_p``) alongside native types.
 
 .. literalinclude:: ../../tests/docs/test_appctx_docs.py
@@ -101,10 +101,10 @@ Solving the KSP
 ~~~~~~~~~~~~~~~
 
 Now we come to actually solving the linear equation :math:`Au=b`.
-To avoid memory leaks, :func:`~.options.set_from_options` does not permanently insert the contents of ``parameters`` into the global options database.
-Instead, we use the :func:`petsctools.inserted_options <.options.inserted_options>` context manager.
+To avoid memory leaks, :func:`petsctools.set_from_options` does not permanently insert the contents of ``parameters`` into the global options database.
+Instead, we use the :func:`petsctools.inserted_options` context manager.
 On entry, this context manager inserts the contents of ``parameters`` into the global database, and on exit it removes them again.
-This means that we need to use the :func:`~.options.inserted_options` context manager whenever these entries will be needed, for example during the solve when the KSP and PC are being set up.
+This means that we need to use the :func:`petsctools.inserted_options` context manager whenever these entries will be needed, for example during the solve when the KSP and PC are being set up.
 
 .. literalinclude:: ../../tests/docs/test_appctx_docs.py
     :language: python3

docs/source/conf.py

@@ -42,6 +42,8 @@
     "path": "../../petsctools",
     "destination": "generated",
 }]
+apidoc_module_first = True
+apidoc_separate_modules = True
 
 # -- sphinx.ext.intersphinx configuration -------------------------------------
 

docs/source/index.rst

@@ -7,7 +7,6 @@ petsctools provides Pythonic extensions for petsc4py and slepc4py.
    :caption: Contents
    :maxdepth: 2
 
-   examples
-   cython
    appctx
+   cython
    generated/modules

petsctools/__init__.py

@@ -1,4 +1,6 @@
-from .config import (  # noqa: F401
+# ruff: noqa I001  (don't reorder imports)
+
+from .config import (
     get_config,
     get_external_packages,
     get_petsc_arch,
@@ -7,26 +9,49 @@
     get_petscconf_h,
     get_petscvariables,
 )
-from .exceptions import (  # noqa: F401
+__all__ = [
+    "get_config",
+    "get_external_packages",
+    "get_petsc_arch",
+    "get_petsc_dir",
+    "get_petsc_dirs",
+    "get_petscconf_h",
+    "get_petscvariables",
+]
+from .exceptions import (
     InvalidEnvironmentException,
     InvalidPetscVersionException,
     MissingPetscException,
     PetscToolsException,
 )
+__all__ += [
+    "InvalidEnvironmentException",
+    "InvalidPetscVersionException",
+    "MissingPetscException",
+    "PetscToolsException",
+]
 from .utils import PETSC4PY_INSTALLED
+__all__ += ["PETSC4PY_INSTALLED"]
 
 # Now conditionally import the functions that depend on petsc4py. If petsc4py
 # is not available then attempting to access these attributes will raise an
 # informative error.
 if PETSC4PY_INSTALLED:
-    from .citation import (  # noqa: F401
+    from .citation import (
         add_citation,
         cite,
         print_citations_at_exit,
     )
-    from .config import get_blas_library  # noqa: F401
-    from .init import init  # noqa: F401
-    from .options import (  # noqa: F401
+    __all__ += [
+        "add_citation",
+        "cite",
+        "print_citations_at_exit",
+    ]
+    from .config import get_blas_library
+    __all__ += ["get_blas_library"]
+    from .init import init
+    __all__ += ["init"]
+    from .options import (
         DefaultOptionSet,
         Options,
         OptionsManager,
@@ -41,7 +66,23 @@
         set_default_parameter,
         set_from_options,
     )
-    from .pc import PCBase  # noqa: F401
+    __all__ += [
+        "DefaultOptionSet",
+        "Options",
+        "OptionsManager",
+        "attach_options",
+        "flatten_parameters",
+        "get_commandline_options",
+        "get_options",
+        "has_options",
+        "inserted_options",
+        "is_set_from_options",
+        "petscobj2str",
+        "set_default_parameter",
+        "set_from_options",
+    ]
+    from .pc import PCBase
+    __all__ += ["PCBase"]
 else:
 
     def __getattr__(name):

petsctools/options.py

@@ -137,8 +137,7 @@ def munge(keys):
 
 def _warn_unused_options(all_options: Iterable, used_options: Iterable,
                          options_prefix: str = ""):
-    """
-    Raise warnings for PETSc options which were not used.
+    """Raise warnings for PETSc options which were not used.
 
     This is meant only as a weakref.finalize callback for the
     :class:`OptionsManager`.
@@ -153,10 +152,6 @@ def _warn_unused_options(all_options: Iterable, used_options: Iterable,
     options_prefix :
         The options_prefix of the :class:`OptionsManager`.
 
-    Raises
-    ------
-        PetscToolsWarning :
-            For every entry in all_options which is not in used_options.
     """
     unused_options = set(all_options) - set(used_options)
 
@@ -284,8 +279,8 @@ def get_default_options(default_options_set: DefaultOptionSet,
     default_options_set
         The :class:`DefaultOptionSet` which defines the shared options.
     options
-        The ``PETSc.Options`` database to use. If not provided then the global
-        database will be used.
+        The :class:`PETSc.Options <petsc4py.PETSc.Options>` database to use. If
+        not provided then the global database will be used.
 
     Returns
     -------
@@ -294,6 +289,7 @@ def get_default_options(default_options_set: DefaultOptionSet,
     See Also
     --------
     DefaultOptionSet
+
     """
     if options is None:
         from petsc4py import PETSc
@@ -567,16 +563,14 @@ def set_from_options(self, petsc_obj):
         this OptionsManager's ``parameters`` are inserted into the global
         :class:`PETSc.Options`.
 
+        A :class:`~.PetscToolsWarning` is raised if the method has already
+        been called.
+
         Parameters
         ----------
         petsc_obj
             The PETSc object to call setFromOptions on.
 
-        Raises
-        ------
-        PetscToolsWarning
-            If this method has already been called.
-
         """
         # Matt says: "Only ever call setFromOptions once".  This
         # function ensures we do so.
@@ -808,7 +802,7 @@ def get_options(obj: petsc4py.PETSc.Object) -> OptionsManager:
 
     Raises
     ------
-    PetscToolsException
+    petsctools.PetscToolsException
         If the object does not have an :class:`OptionsManager`.
 
     See Also
@@ -841,7 +835,7 @@ def set_default_parameter(
 
     Raises
     ------
-    PetscToolsException
+    petsctools.PetscToolsException
         If the object does not have an :class:`OptionsManager`.
 
     See Also
@@ -888,14 +882,9 @@ def set_from_options(
 
     Raises
     ------
-    PetscToolsException
+    petsctools.PetscToolsException
         If the neither ``parameters`` nor ``options_prefix`` are
         provided but ``obj`` does not have an :class:`OptionsManager` attached.
-    PetscToolsException
-        If the either ``parameters`` or ``options_prefix`` are provided
-        but ``obj`` already has an :class:`OptionsManager` attached.
-    PetscToolsWarning
-        If set_from_options has already been called for this object.
 
     See Also
     --------
@@ -951,7 +940,7 @@ def is_set_from_options(obj: petsc4py.PETSc.Object) -> bool:
 
     Raises
     ------
-    PetscToolsException
+    petsctools.PetscToolsException
         If the object does not have an :class:`OptionsManager`.
 
     See Also
@@ -995,7 +984,7 @@ def inserted_options(
 
     Raises
     ------
-    PetscToolsException
+    petsctools.PetscToolsException
         If the object does not have an :class:`OptionsManager`.
 
     See Also
@@ -1082,6 +1071,7 @@ def __getitem__(self, option: str | AppContextKey, /) -> Any:
         ------
         KeyError
             If the ``Options`` does not contain a value for ``option``.
+
         """
         # might raise a KeyError, which we want
         value = super().__getitem__(option)
@@ -1141,15 +1131,17 @@ def get(
         or the ``default`` value if ``option`` is not found in the
         global options database.
 
-        If this ``Options`` instance has a prefix then the value
-        corresponding to the key ``self.prefix + option`` will be returned.
+        If this :class:`petsctools.Options` instance has a prefix then the
+        value corresponding to the key ``self.prefix + option`` will be
+        returned.
 
         Parameters
         ----------
         option :
             The PETSc option or key.
         default :
-            The value to return if ``option`` is not in the ``Options``
+            The value to return if ``option`` is not in the
+            :class:`petsctools.Options`.
 
         Returns
         -------