Skip to content

Commit 7bd8704

Browse files
OriolAbrilOriolAbril
authored
Several API doc improvements (#5367)
* work on docs * add examples link * run pre-commit * update release notes * Update RELEASE-NOTES.md
1 parent be3f77e commit 7bd8704

14 files changed

+103
-42
lines changed

‎RELEASE-NOTES.md

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -128,6 +128,13 @@ This includes API changes we did not warn about since at least `3.11.0` (2021-01
128128
- `softmax` and `log_softmax` functions added to `math` module (see [#5279](https://github.com/pymc-devs/pymc/pull/5279)).
129129
- ...
130130

131+
## Documentation
132+
- Switched to the [pydata-sphinx-theme](https://pydata-sphinx-theme.readthedocs.io/en/latest/)
133+
- 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,
134+
sphinx-copybutton and sphinx-remove-toctrees.
135+
- Separated the builds of the example notebooks and of the versioned docs.
136+
- Restructured the documentation to facilitate learning paths
137+
- Updated API docs to document objects at the path users should use to import them
131138

132139
### Internal changes
133140
- ⚠ PyMC now requires Scipy version `>= 1.4.1` (see [4857](https://github.com/pymc-devs/pymc/pull/4857)).

‎conda-envs/environment-dev-py37.yml

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -31,3 +31,4 @@ dependencies:
3131
- pip:
3232
- polyagamma
3333
- sphinx-design
34+
- sphinx-remove-toctrees

‎conda-envs/environment-dev-py38.yml

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -31,3 +31,4 @@ dependencies:
3131
- pip:
3232
- polyagamma
3333
- sphinx-design
34+
- sphinx-remove-toctrees

‎conda-envs/environment-dev-py39.yml

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -31,3 +31,4 @@ dependencies:
3131
- pip:
3232
- polyagamma
3333
- sphinx-design
34+
- sphinx-remove-toctrees

‎conda-envs/windows-environment-dev-py38.yml

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -33,3 +33,4 @@ dependencies:
3333
- watermark
3434
- pip:
3535
- sphinx-design
36+
- sphinx-remove-toctrees

‎docs/source/_templates/autosummary/class.rst

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
{{ fullname | escape | underline}}
2+
3+
.. currentmodule:: {{ module }}
4+
5+
.. autoclass:: {{ objname }}
6+
7+
{% block methods %}
8+
{% if methods %}
9+
10+
.. rubric:: Methods
11+
12+
.. autosummary::
13+
:toctree: classmethods
14+
15+
{% for item in methods %}
16+
{{ objname }}.{{ item }}
17+
{%- endfor %}
18+
{% endif %}
19+
{% endblock %}
20+
21+
{% block attributes %}
22+
{% if attributes %}
23+
.. rubric:: Attributes
24+
25+
.. autosummary::
26+
{% for item in attributes %}
27+
~{{ name }}.{{ item }}
28+
{%- endfor %}
29+
{% endif %}
30+
{% endblock %}

‎docs/source/api/gp.rst

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
1-
Gaussian Processes API
2-
----------------------
1+
Gaussian Processes
2+
------------------
33

4-
.. currentmodule:: pymc.gp.gp
4+
.. automodule:: pymc.gp
55

66
.. toctree::
77

‎docs/source/api/gp/cov.rst

Lines changed: 18 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -2,24 +2,23 @@
22
Covariance Functions
33
********************
44

5-
.. currentmodule:: pymc.gp.cov
5+
.. automodule:: pymc.gp.cov
66
.. autosummary::
7-
Constant
8-
WhiteNoise
9-
ExpQuad
10-
RatQuad
11-
Exponential
12-
Matern52
13-
Matern32
14-
Linear
15-
Polynomial
16-
Cosine
17-
Periodic
18-
WarpedInput
19-
Gibbs
20-
Coregion
21-
ScaledCov
22-
Kron
7+
:toctree: generated
238

24-
.. automodule:: pymc.gp.cov
25-
:members:
9+
Constant
10+
WhiteNoise
11+
ExpQuad
12+
RatQuad
13+
Exponential
14+
Matern52
15+
Matern32
16+
Linear
17+
Polynomial
18+
Cosine
19+
Periodic
20+
WarpedInput
21+
Gibbs
22+
Coregion
23+
ScaledCov
24+
Kron

‎docs/source/api/gp/implementations.rst

Lines changed: 5 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -2,14 +2,13 @@
22
Implementations
33
***************
44

5-
.. currentmodule:: pymc.gp.gp
5+
.. currentmodule:: pymc.gp
66
.. autosummary::
7+
:toctree: generated
8+
79
Latent
8-
Marginal
910
LatentKron
11+
Marginal
1012
MarginalKron
11-
MarginalSparse
13+
MarginalApprox
1214
TP
13-
14-
.. automodule:: pymc.gp.gp
15-
:members:

‎docs/source/api/gp/mean.rst

Lines changed: 2 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -2,12 +2,10 @@
22
Mean Functions
33
**************
44

5-
.. currentmodule:: pymc.gp.mean
5+
.. automodule:: pymc.gp.mean
66
.. autosummary::
7+
:toctree: generated
78

89
Zero
910
Constant
1011
Linear
11-
12-
.. automodule:: pymc.gp.mean
13-
:members:

‎docs/source/conf.py

Lines changed: 22 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -48,16 +48,32 @@
4848
"sphinx_design",
4949
"notfound.extension",
5050
"sphinx_copybutton",
51+
"sphinx_remove_toctrees",
5152
]
5253

5354
# Don't auto-generate summary for class members.
5455
numpydoc_show_class_members = False
56+
autosummary_generate = True
57+
autodoc_typehints = "none"
58+
remove_from_toctrees = ["**/classmethods/*"]
59+
60+
numpydoc_xref_param_type = True
61+
# fmt: off
62+
numpydoc_xref_ignore = {
63+
"of", "or", "optional", "default", "numeric", "type", "scalar", "1D", "2D", "3D", "nD", "array",
64+
"instance"
65+
}
66+
# fmt: on
67+
numpydoc_xref_aliases = {
68+
"TensorVariable": ":class:`~aesara.tensor.TensorVariable`",
69+
"RandomVariable": ":class:`~aesara.tensor.random.RandomVariable`",
70+
"ndarray": ":class:`~numpy.ndarray`",
71+
"Covariance": ":mod:`Covariance <pymc.gp.cov>`",
72+
"Mean": ":mod:`Mean <pymc.gp.mean>`",
73+
}
5574

5675
# Show the documentation of __init__ and the class docstring
57-
autoclass_content = "both"
58-
59-
# Do not show the return type as seperate section
60-
napoleon_use_rtype = False
76+
# autoclass_content = "both"
6177

6278
# Add any paths that contain templates here, relative to this directory.
6379
templates_path = ["_templates"]
@@ -162,6 +178,7 @@
162178
"nb": ("https://pymc-examples.readthedocs.io/en/latest/", None),
163179
"myst": ("https://myst-parser.readthedocs.io/en/latest", None),
164180
"myst-nb": ("https://myst-nb.readthedocs.io/en/latest/", None),
181+
"python": ("https://docs.python.org/3/", None),
165182
}
166183

167184

@@ -195,7 +212,7 @@
195212
},
196213
],
197214
"show_prev_next": False,
198-
"navbar_align": "content",
215+
"navbar_align": "left",
199216
"navbar_start": ["navbar-logo", "navbar-version"],
200217
"navbar_end": ["search-field.html", "navbar-icon-links.html"],
201218
"search_bar_text": "Search...",

‎docs/source/index.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -155,6 +155,7 @@ See [Google Scholar](https://scholar.google.de/scholar?oi=bibs&hl=en&authuser=1&
155155

156156
installation
157157
learning
158+
Examples <https://docs.pymc.io/projects/examples/en/latest/>
158159
api
159160
community
160161
contributing/index

‎pymc/distributions/continuous.py

Lines changed: 10 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -263,6 +263,7 @@ class Uniform(BoundedContinuous):
263263
f(x \mid lower, upper) = \frac{1}{upper-lower}
264264
265265
.. plot::
266+
:context: close-figs
266267
267268
import matplotlib.pyplot as plt
268269
import numpy as np
@@ -289,10 +290,10 @@ class Uniform(BoundedContinuous):
289290
290291
Parameters
291292
----------
292-
lower: float
293-
Lower limit.
294-
upper: float
295-
Upper limit.
293+
lower : float, optional
294+
Lower limit. Defaults to 0.
295+
upper : float, optional
296+
Upper limit. Defaults to 1.
296297
"""
297298
rv_op = uniform
298299
bound_args_indices = (3, 4) # Lower, Upper
@@ -317,9 +318,13 @@ def logcdf(value, lower, upper):
317318
318319
Parameters
319320
----------
320-
value: numeric or np.ndarray or `TensorVariable`
321+
value : numeric or ndarray or TensorVariable
321322
Value(s) for which log CDF is calculated. If the log CDF for multiple
322323
values are desired the values must be provided in a numpy array or `TensorVariable`.
324+
lower : float, optional
325+
Lower limit. Defaults to 0.
326+
upper : float, optional
327+
Upper limit. Defaults to 1.
323328
324329
Returns
325330
-------

‎requirements-dev.txt

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -22,5 +22,6 @@ scipy>1.4.1
2222
sphinx-copybutton
2323
sphinx-design
2424
sphinx-notfound-page
25+
sphinx-remove-toctrees
2526
sphinx>=1.5
2627
typing-extensions>=3.7.4

0 commit comments

Comments
 (0)