diff --git a/RELEASE-NOTES.md b/RELEASE-NOTES.md index c90480f5ea..09c5301892 100644 --- a/RELEASE-NOTES.md +++ b/RELEASE-NOTES.md @@ -127,6 +127,13 @@ This includes API changes we did not warn about since at least `3.11.0` (2021-01 - Nested models now inherit the parent model's coordinates. [#5344](https://github.com/pymc-devs/pymc/pull/5344) - ... +## 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 index 9b07b0f4af..80f6fc8bab 100644 --- a/conda-envs/environment-dev-py37.yml +++ b/conda-envs/environment-dev-py37.yml @@ -29,3 +29,4 @@ dependencies: - typing-extensions - pip: - sphinx-design + - sphinx-remove-toctrees diff --git a/conda-envs/environment-dev-py38.yml b/conda-envs/environment-dev-py38.yml index 17c3f42869..69f562a5ca 100644 --- a/conda-envs/environment-dev-py38.yml +++ b/conda-envs/environment-dev-py38.yml @@ -29,3 +29,4 @@ dependencies: - typing-extensions>=3.7.4 - pip: - sphinx-design + - sphinx-remove-toctrees diff --git a/conda-envs/environment-dev-py39.yml b/conda-envs/environment-dev-py39.yml index cbdc89390a..e098c48d23 100644 --- a/conda-envs/environment-dev-py39.yml +++ b/conda-envs/environment-dev-py39.yml @@ -29,3 +29,4 @@ dependencies: - typing-extensions>=3.7.4 - pip: - sphinx-design + - sphinx-remove-toctrees diff --git a/conda-envs/windows-environment-dev-py38.yml b/conda-envs/windows-environment-dev-py38.yml index e7f3786b38..a83652c351 100644 --- 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 new file mode 100644 index 0000000000..ad5436f826 --- /dev/null +++ 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 index 284e83144f..6b2646fbfe 100644 --- 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 index 024832e0b2..5ae9501603 100644 --- 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 index 8166f19cca..3b9f972845 100644 --- 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 index 9ff7d921fe..e734fcec1a 100644 --- 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 index 4c88dc22be..641c49a282 100755 --- 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 `", + "Mean": ":mod:`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 index a50ce27609..2446ed79ec 100644 --- 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 api community contributing/index diff --git a/pymc/distributions/continuous.py b/pymc/distributions/continuous.py index 987eadaf7c..dbdfbe4791 100644 --- 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 index 8582d96bd1..aaa7c489a5 100644 --- a/requirements-dev.txt +++ b/requirements-dev.txt @@ -21,5 +21,6 @@ scipy>1.4.1 sphinx-copybutton sphinx-design sphinx-notfound-page +sphinx-remove-toctrees sphinx>=1.5 typing-extensions>=3.7.4