Skip to content

Commit 7d974d1

Browse files
authored
some small improvements to get everything ready for the sprint (#5461)
* some small improvements to get everything ready for the sprint * clarify a couple points in the jupyter style guide * add note on diataxis type category
1 parent e018309 commit 7d974d1

File tree

2 files changed

+20
-10
lines changed

2 files changed

+20
-10
lines changed

docs/source/conf.py

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -70,11 +70,12 @@
7070
"ndarray": ":class:`~numpy.ndarray`",
7171
"Covariance": ":mod:`Covariance <pymc.gp.cov>`",
7272
"Mean": ":mod:`Mean <pymc.gp.mean>`",
73-
"InferenceData": ":class:`arviz.InferenceData`",
73+
"InferenceData": ":class:`~arviz.InferenceData`",
7474
"MultiTrace": ":class:`~pymc.backends.base.MultiTrace`",
7575
"BaseTrace": ":class:`~pymc.backends.base.BaseTrace`",
7676
"Point": ":class:`~pymc.Point`",
7777
"SMC_kernel": ":ref:`SMC Kernel <smc_kernels>`",
78+
"Aesara_Op": ":class:`Aesara Op <aesara.graph.op.Op>`",
7879
}
7980

8081
# Show the documentation of __init__ and the class docstring
@@ -178,7 +179,7 @@
178179
intersphinx_mapping = {
179180
"arviz": ("https://arviz-devs.github.io/arviz/", None),
180181
"aesara": ("https://aesara.readthedocs.io/en/latest/", None),
181-
"aeppl": ("https://aesara-devs.github.io/aeppl/", None),
182+
"aeppl": ("https://aeppl.readthedocs.io/en/latest/", None),
182183
"numpy": ("https://numpy.org/doc/stable/", None),
183184
"nb": ("https://pymc-examples.readthedocs.io/en/latest/", None),
184185
"myst": ("https://myst-parser.readthedocs.io/en/latest", None),

docs/source/contributing/jupyter_style.md

Lines changed: 17 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -47,13 +47,13 @@ This guide does not teach nor cover MyST extensively, only gives some opinionate
4747
### Variable names
4848

4949
* Above all, stay consistent with variable names within the notebook. Notebooks using multiple names for the same variable will not be merged.
50-
5150
* Use meaningful variable names wherever possible. Our users come from different backgrounds and not everyone is familiar with the same naming conventions.
52-
51+
- Annotate dimensions too. Notebooks are published to be read, so even if the shape is derived
52+
from the inputs or you don't like to use named dims and don't use them in your presonal
53+
code, notebooks must use dims, even if annotating and not setting the shape.
54+
It makes the code easier to follow, especially for newcomers.
5355
* Sometimes it makes sense to use Greek letters to refer to variables, for example when writing equations, as this makes them easier to read. In that case, use LaTeX to insert the Greek letter like this `$\theta$` instead of using Unicode like `θ`.
54-
5556
* If you need to use Greek letter variable names inside the code, please spell them out instead of using unicode. For example, `theta`, not `θ`.
56-
5757
* When using non meaningful names such as single letters, add bullet points with a 1-2 sentence description of each variable below the equation where they are first introduced.
5858

5959
Choosing variable names can sometimes be difficult, tedious or annoying.
@@ -174,7 +174,7 @@ The first cell of all example notebooks should have a MyST target, a level 1 mar
174174
The syntax is as follows:
175175

176176
```markdown
177-
(notebook_id)=
177+
(notebook_name)=
178178
# Notebook Title
179179

180180
:::{post} Aug 31, 2021
@@ -186,14 +186,23 @@ The syntax is as follows:
186186

187187
The date should correspond to the latest update/execution date, at least roughly (it's not a problem if the date is a few days off due to the review process before merging the PR). This will allow users to see which notebooks have been updated lately and will help the PyMC team make sure no notebook is left outdated for too long.
188188

189-
The {ref}`MyST target <myst:syntax/targets>`
189+
The {ref}`MyST target <myst:syntax/targets>` (the `(notebook_name)=` bit)
190190
is important to ease referencing and linking notebooks between each other.
191+
It must be notebook specific, for example its file name.
191192

192193
Tags can be anything, but we ask you to try to use [existing tags](https://github.com/pymc-devs/pymc/wiki/Categories-and-Tags-for-PyMC-Examples)
193194
to avoid the tag list from getting too long.
194195

195-
Each notebook should have a single category indicating the level of the notebook.
196-
Choose a category from [existing categories](https://github.com/pymc-devs/pymc/wiki/Categories-and-Tags-for-PyMC-Examples#categories).
196+
Each notebook should have a one or two categories indicating:
197+
* the level of the notebook (required):
198+
- `beginner` (standing crow icon)
199+
- `intermediate` (flying dove icon)
200+
- `advanced` (dragon icon)
201+
* the [diataxis](https://diataxis.fr/) type (optional for old notebooks):
202+
- tutorial
203+
- how to guide
204+
- explanation
205+
- reference
197206

198207
Authors should list people who authored, adapted or updated the notebook. See {ref}`jupyter_authors`
199208
for more details.

0 commit comments

Comments
 (0)