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
Copy file name to clipboardExpand all lines: docs/development/docsguide.md
+18-5Lines changed: 18 additions & 5 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -2,7 +2,9 @@
2
2
3
3
## Vision
4
4
5
-
We believe a clear documentation is important to community building, reproducibility, and transparency in our open-source project. To make it easier to write our documentation in a consistent way, here we outline a brief vision for our documentation based heavily on a few common resources.
5
+
We believe a clear documentation is important to community building, reproducibility, and transparency in our open-source
6
+
project. To make it easier to write our documentation in a consistent way, here we outline a brief vision for our
7
+
documentation based heavily on a few common resources.
6
8
7
9
```{note}
8
10
TODO: outline functions of the documentation based on resources
@@ -17,15 +19,26 @@ TODO: outline functions of the documentation based on resources
17
19
18
20
## Notebook execution
19
21
20
-
We run the notebooks in our documentation using [MyST-NB](https://myst-nb.readthedocs.io/en/latest/index.html). Here is a table showing the latest notebook execution:
22
+
We run the notebooks in our documentation using [MyST-NB](https://myst-nb.readthedocs.io/en/latest/index.html). Here is
23
+
a table showing the latest notebook execution:
21
24
22
25
```{nb-exec-table}
23
26
24
27
```
25
28
26
29
## Style guide
27
30
28
-
-**Write out `parcels.class.method` in tutorials and how-to guides** so that we can see which classes and methods are part of Parcels. Because in the alternative (using `from parcels import class`) the use of `class` in a cell further along is not obviously part of `parcels`.
29
-
-[**Avoid too much Repitition In Documentation**](https://www.writethedocs.org/guide/writing/docs-principles/#arid): tutorials and how-to guides notebooks will often have repetition of the general **Parcels** steps, which is fine because we want readers to see the changes to a specific class or method in the context of the simulation, e.g. `Particle` and `Kernel` are often customised together, which must be defined before the `ParticleSet.execute()`. We try to limit each page in the documentation to a small number of examples.
31
+
-**Write out `parcels.class.method` in tutorials and how-to guides** so that we can see which classes and methods are
32
+
part of Parcels. Because in the alternative (using `from parcels import class`) the use of `class` in a cell further
33
+
along is not obviously part of `parcels`.
34
+
-[**Avoid too much Repitition In Documentation**](https://www.writethedocs.org/guide/writing/docs-principles/#arid):
35
+
tutorials and how-to guides notebooks will often have repetition of the general **Parcels** steps, which is fine because
36
+
we want readers to see the changes to a specific class or method in the context of the simulation, e.g. `Particle` and
37
+
`Kernel` are often customised together, which must be defined before the `ParticleSet.execute()`. We try to limit each
38
+
page in the documentation to a small number of examples.
30
39
-**Import packages at the top of the section in which they are first used** to show what they are used for.
31
-
-**Write documentation in first person plural ("we").** In our open source code, tutorials and guides can be written by any developer or user, so the documentation teaches all of us how to do something with Parcels. Sometimes it can be more natural to take on the tone of a teacher, writing to a student/learner, in which case it is okay to use "you". Please refrain from using impersonal subjects such as "the user".
40
+
-**Write documentation in first person plural ("we").** In our open source code, tutorials and guides can be written
41
+
by any developer or user, so the documentation teaches all of us how to do something with Parcels. Sometimes it can be
42
+
more natural to take on the tone of a teacher, writing to a student/learner, in which case it is okay to use "you".
43
+
Please refrain from using impersonal subjects such as "the user".
44
+
- We recommend hard wrapping prose in markdown so that reading it becomes easier in any editor.
0 commit comments