You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
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
Copy file name to clipboardExpand all lines: docs/source/contributing/jupyter_style.md
+17-8Lines changed: 17 additions & 8 deletions
Original file line number
Diff line number
Diff line change
@@ -47,13 +47,13 @@ This guide does not teach nor cover MyST extensively, only gives some opinionate
47
47
### Variable names
48
48
49
49
* Above all, stay consistent with variable names within the notebook. Notebooks using multiple names for the same variable will not be merged.
50
-
51
50
* 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.
53
55
* 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
-
55
56
* 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
-
57
57
* 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.
58
58
59
59
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
174
174
The syntax is as follows:
175
175
176
176
```markdown
177
-
(notebook_id)=
177
+
(notebook_name)=
178
178
# Notebook Title
179
179
180
180
:::{post} Aug 31, 2021
@@ -186,14 +186,23 @@ The syntax is as follows:
186
186
187
187
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.
188
188
189
-
The {ref}`MyST target <myst:syntax/targets>`
189
+
The {ref}`MyST target <myst:syntax/targets>` (the `(notebook_name)=` bit)
190
190
is important to ease referencing and linking notebooks between each other.
191
+
It must be notebook specific, for example its file name.
191
192
192
193
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)
193
194
to avoid the tag list from getting too long.
194
195
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
197
206
198
207
Authors should list people who authored, adapted or updated the notebook. See {ref}`jupyter_authors`
0 commit comments