Several API doc improvements (#5367)

OriolAbril · web-flow · commit 7bd87049bb4f · 2022-01-21T11:49:13.000+02:00
* work on docs

* add examples link

* run pre-commit

* update release notes

* Update RELEASE-NOTES.md
diff --git a/RELEASE-NOTES.md b/RELEASE-NOTES.md
@@ -128,6 +128,13 @@ This includes API changes we did not warn about since at least `3.11.0` (2021-01
 - `softmax` and `log_softmax` functions added to `math` module (see [#5279](https://github.com/pymc-devs/pymc/pull/5279)).
 - ...
 
+## Documentation
+- Switched to the [pydata-sphinx-theme](https://pydata-sphinx-theme.readthedocs.io/en/latest/)
+- Updated our documentation tooling to use [MyST](https://myst-parser.readthedocs.io/en/latest/), [MyST-NB](https://myst-nb.readthedocs.io/en/latest/), sphinx-design, notfound.extension,
+  sphinx-copybutton and sphinx-remove-toctrees.
+- Separated the builds of the example notebooks and of the versioned docs.
+- Restructured the documentation to facilitate learning paths
+- Updated API docs to document objects at the path users should use to import them
 
 ### Internal changes
 - ⚠ PyMC now requires Scipy version `>= 1.4.1` (see [4857](https://github.com/pymc-devs/pymc/pull/4857)).
diff --git a/conda-envs/environment-dev-py37.yml b/conda-envs/environment-dev-py37.yml
@@ -31,3 +31,4 @@ dependencies:
 - pip:
   - polyagamma
   - sphinx-design
+  - sphinx-remove-toctrees
diff --git a/conda-envs/environment-dev-py38.yml b/conda-envs/environment-dev-py38.yml
@@ -31,3 +31,4 @@ dependencies:
 - pip:
   - polyagamma
   - sphinx-design
+  - sphinx-remove-toctrees
diff --git a/conda-envs/environment-dev-py39.yml b/conda-envs/environment-dev-py39.yml
@@ -31,3 +31,4 @@ dependencies:
 - pip:
   - polyagamma
   - sphinx-design
+  - sphinx-remove-toctrees
diff --git a/conda-envs/windows-environment-dev-py38.yml b/conda-envs/windows-environment-dev-py38.yml
@@ -33,3 +33,4 @@ dependencies:
 - watermark
 - pip:
   - sphinx-design
+  - sphinx-remove-toctrees
diff --git a/docs/source/_templates/autosummary/class.rst b/docs/source/_templates/autosummary/class.rst
@@ -0,0 +1,30 @@
+{{ fullname | escape | underline}}
+
+.. currentmodule:: {{ module }}
+
+.. autoclass:: {{ objname }}
+
+   {% block methods %}
+   {% if methods %}
+
+   .. rubric:: Methods
+
+   .. autosummary::
+      :toctree: classmethods
+
+   {% for item in methods %}
+      {{ objname }}.{{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+   {% block attributes %}
+   {% if attributes %}
+   .. rubric:: Attributes
+
+   .. autosummary::
+   {% for item in attributes %}
+      ~{{ name }}.{{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
diff --git a/docs/source/api/gp.rst b/docs/source/api/gp.rst
@@ -1,7 +1,7 @@
-Gaussian Processes API
-----------------------
+Gaussian Processes
+------------------
 
-.. currentmodule:: pymc.gp.gp
+.. automodule:: pymc.gp
 
 .. toctree::
 
diff --git a/docs/source/api/gp/cov.rst b/docs/source/api/gp/cov.rst
@@ -2,24 +2,23 @@
 Covariance Functions
 ********************
 
-.. currentmodule:: pymc.gp.cov
+.. automodule:: pymc.gp.cov
 .. autosummary::
-  Constant
-  WhiteNoise
-  ExpQuad
-  RatQuad
-  Exponential
-  Matern52
-  Matern32
-  Linear
-  Polynomial
-  Cosine
-  Periodic
-  WarpedInput
-  Gibbs
-  Coregion
-  ScaledCov
-  Kron
+   :toctree: generated
 
-.. automodule:: pymc.gp.cov
-   :members:
+    Constant
+    WhiteNoise
+    ExpQuad
+    RatQuad
+    Exponential
+    Matern52
+    Matern32
+    Linear
+    Polynomial
+    Cosine
+    Periodic
+    WarpedInput
+    Gibbs
+    Coregion
+    ScaledCov
+    Kron
diff --git a/docs/source/api/gp/implementations.rst b/docs/source/api/gp/implementations.rst
@@ -2,14 +2,13 @@
 Implementations
 ***************
 
-.. currentmodule:: pymc.gp.gp
+.. currentmodule:: pymc.gp
 .. autosummary::
+   :toctree: generated
+
    Latent
-   Marginal
    LatentKron
+   Marginal
    MarginalKron
-   MarginalSparse
+   MarginalApprox
    TP
-
-.. automodule:: pymc.gp.gp
-   :members:
diff --git a/docs/source/api/gp/mean.rst b/docs/source/api/gp/mean.rst
@@ -2,12 +2,10 @@
 Mean Functions
 **************
 
-.. currentmodule:: pymc.gp.mean
+.. automodule:: pymc.gp.mean
 .. autosummary::
+   :toctree: generated
 
    Zero
    Constant
    Linear
-
-.. automodule:: pymc.gp.mean
-   :members:
diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -48,16 +48,32 @@
     "sphinx_design",
     "notfound.extension",
     "sphinx_copybutton",
+    "sphinx_remove_toctrees",
 ]
 
 # Don't auto-generate summary for class members.
 numpydoc_show_class_members = False
+autosummary_generate = True
+autodoc_typehints = "none"
+remove_from_toctrees = ["**/classmethods/*"]
+
+numpydoc_xref_param_type = True
+# fmt: off
+numpydoc_xref_ignore = {
+    "of", "or", "optional", "default", "numeric", "type", "scalar", "1D", "2D", "3D", "nD", "array",
+    "instance"
+}
+# fmt: on
+numpydoc_xref_aliases = {
+    "TensorVariable": ":class:`~aesara.tensor.TensorVariable`",
+    "RandomVariable": ":class:`~aesara.tensor.random.RandomVariable`",
+    "ndarray": ":class:`~numpy.ndarray`",
+    "Covariance": ":mod:`Covariance <pymc.gp.cov>`",
+    "Mean": ":mod:`Mean <pymc.gp.mean>`",
+}
 
 # Show the documentation of __init__ and the class docstring
-autoclass_content = "both"
-
-# Do not show the return type as seperate section
-napoleon_use_rtype = False
+# autoclass_content = "both"
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ["_templates"]
@@ -162,6 +178,7 @@
     "nb": ("https://pymc-examples.readthedocs.io/en/latest/", None),
     "myst": ("https://myst-parser.readthedocs.io/en/latest", None),
     "myst-nb": ("https://myst-nb.readthedocs.io/en/latest/", None),
+    "python": ("https://docs.python.org/3/", None),
 }
 
 
@@ -195,7 +212,7 @@
         },
     ],
     "show_prev_next": False,
-    "navbar_align": "content",
+    "navbar_align": "left",
     "navbar_start": ["navbar-logo", "navbar-version"],
     "navbar_end": ["search-field.html", "navbar-icon-links.html"],
     "search_bar_text": "Search...",
diff --git a/docs/source/index.md b/docs/source/index.md
@@ -155,6 +155,7 @@ See [Google Scholar](https://scholar.google.de/scholar?oi=bibs&hl=en&authuser=1&
 
 installation
 learning
+Examples <https://docs.pymc.io/projects/examples/en/latest/>
 api
 community
 contributing/index
diff --git a/pymc/distributions/continuous.py b/pymc/distributions/continuous.py
@@ -263,6 +263,7 @@ class Uniform(BoundedContinuous):
        f(x \mid lower, upper) = \frac{1}{upper-lower}
 
     .. plot::
+        :context: close-figs
 
         import matplotlib.pyplot as plt
         import numpy as np
@@ -289,10 +290,10 @@ class Uniform(BoundedContinuous):
 
     Parameters
     ----------
-    lower: float
-        Lower limit.
-    upper: float
-        Upper limit.
+    lower : float, optional
+        Lower limit. Defaults to 0.
+    upper : float, optional
+        Upper limit. Defaults to 1.
     """
     rv_op = uniform
     bound_args_indices = (3, 4)  # Lower, Upper
@@ -317,9 +318,13 @@ def logcdf(value, lower, upper):
 
         Parameters
         ----------
-        value: numeric or np.ndarray or `TensorVariable`
+        value : numeric or ndarray or TensorVariable
             Value(s) for which log CDF is calculated. If the log CDF for multiple
             values are desired the values must be provided in a numpy array or `TensorVariable`.
+        lower : float, optional
+            Lower limit. Defaults to 0.
+        upper : float, optional
+            Upper limit. Defaults to 1.
 
         Returns
         -------
diff --git a/requirements-dev.txt b/requirements-dev.txt
@@ -22,5 +22,6 @@ scipy>1.4.1
 sphinx-copybutton
 sphinx-design
 sphinx-notfound-page
+sphinx-remove-toctrees
 sphinx>=1.5
 typing-extensions>=3.7.4
