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: documentation/index.md
+6-5Lines changed: 6 additions & 5 deletions
Original file line number
Diff line number
Diff line change
@@ -17,11 +17,12 @@ In the pyOpenSci open peer review process we look for several files and elements
17
17
when evaluating package documentation, including:
18
18
19
19
1.[A clear and to the point **README.md** file](readme-file-best-practices)
20
-
2.**User oriented package documentation** that helps users understand how to install, use and cite your package.
21
-
3.**Package API documentation.** Package API documentation refers to documentation for each class, function, method and attribute that is user-facing (*available for a user to see*) in your package. This mean that your package methods and classes should have [thoughtful docstrings](https://pandas.pydata.org/docs/development/contributing_docstring.html) that describe both the purpose of the code element and each input and output. To help your users better understand how to use your package, you can include short code examples that demonstrate how to use the function or class in each docstring. If you don't know what API documentation means this section of the pyOpenSci Python packaging guide is for you!
22
-
4. A **CONTRIBUTING.md** file that outlines how others can contribute to your package. This file should also link to your development guide and code of conduct. A well-crafted contributing guide will make it much easier for the community to contribute to your project.
23
-
5. A **CODE_OF_CONDUCT.md** file.
24
-
5.**LICENSE.txt file & Citation instructions:** A license file and instructions for citing your package.
20
+
1.**User oriented package documentation** that helps users understand how to install, use and cite your package.
21
+
1.**Tutorials and quick start code examples** that help a user get started using your package.
22
+
1.**Package API documentation.** Package API documentation refers to documentation for each class, function, method and user-facing attribute (*available for a user to see*) in your package. This means that your package methods and classes should have [thoughtful docstrings](https://pandas.pydata.org/docs/development/contributing_docstring.html) that describe both the purpose of the code element and each input and output. To help your users better understand how to use your package, you can include short code examples showing how to use the function or class in each docstring. If you don't know what API documentation means, this section of the pyOpenSci Python packaging guide is for you!
23
+
1. A **CONTRIBUTING.md** file that outlines how others can contribute to your package. This file should also link to your development guide and code of conduct. A well-crafted contributing guide will make it much easier for the community to contribute to your project.
24
+
1. A **CODE_OF_CONDUCT.md** file.
25
+
1.**LICENSE.txt file & Citation instructions:** A license file and instructions for citing your package.
# Best practices for writing user-facing documentation for your Python package
2
2
3
-
In addition to a well designed [README.md file](readme-file-best-practices), and a
4
-
[CONTRIBUTING.md file](contributing-file),
3
+
In addition to a well designed [README.md file](readme-file-best-practices),
4
+
and a [CONTRIBUTING.md file](contributing-file),
5
5
there are several core components of Python package documentation,
6
6
including:
7
7
8
8
***User-facing documentation website:** This refers to easy-to-read documentation that helps a user work with your package. This documentation should help users both install and use the functionality of your package.
9
-
***API documentation:** API documentation is generated from [docstrings](https://pandas.pydata.org/docs/development/contributing_docstring.html) found in your code. Ideally you have docstrings for all user-facing functions, methods and classes in your Python package.
9
+
***API documentation:** The API refers to the functions and classes in a
10
+
package that makes up the user interface. API documentation is generated from [docstrings](https://pandas.pydata.org/docs/development/contributing_docstring.html) found in your
11
+
code. Ideally you have docstrings for all user-facing functions, methods and classes in
12
+
your Python package. We will discuss API's and docstrings in greater detail below.
10
13
11
14
12
-
13
-
```{note}
14
-
Examples of documentation that we love:
15
-
16
-
* [geopandas](https://geopandas.org/en/stable/)
17
-
* [View rst to create landing page](https://raw.githubusercontent.com/geopandas/geopandas/main/doc/source/index.rst)
* [Here is our documentation if you want to see a myST example of a landing page.](https://github.com/pyOpenSci/python-package-guide/blob/main/index.md)
21
-
```
22
-
23
-
In addition to a well designed [README FILE](readme-file-best-practices), and a
24
-
[contributing file](contributing-file),
25
-
there are several core components of Python package documentation,
26
-
including:
27
-
28
-
***User-facing documentation:** This refers to easy-to-read documentation that helps a user work with your package. This documentation should help users both install and use the functionality of your package.
29
-
***API documentation:** API documentation is generated from [docstrings](https://pandas.pydata.org/docs/development/contributing_docstring.html) found in your code. Ideally you have docstrings for all user-facing functions, methods and classes in your Python package.
30
-
31
-
## User-facing documentation for your Python package:
32
-
33
15
User-facing documentation should be published on a easy-to-navigate website. All language should be written with non-developer users in mind. This means
34
16
using language that is less technical.
35
17
36
18
A few tips to make sure your documentation is accessible include:
37
19
38
20
* Whenever possible, define technical terms and jargon.
39
21
* Consider writing instructions for a high-school level reader.
40
-
* Include step by step code examples, tutorials or vignettes that support getting started using your package.
22
+
* Include step-by-step code examples, tutorials or vignettes that support getting started using your package.
41
23
24
+
## Documentation landing page best practices
42
25
26
+
To make it easy for users to find what they need quickly, all packages should
27
+
have 4 elements on the home page of their documentation:
28
+
29
+
***Getting started:** This section should provide the user with a quick start for installing your package. A small example of how to use the package is good to have here as well.
30
+
***About:** Describe your project, state project goals and what it does.
31
+
***Community:** Instructions for how to help and/or get involved. This section might include a development guide.
32
+
***Documentation:** The actual project documentation. You may have two sections of documentation - the user facing documentation and your API reference.
33
+
34
+
NOTE: in many cases you can include your **README** file and your **CONTRIBUTING** files
35
+
in your documentation given those files may have some of the components listed above.
36
+
37
+
`````{tip}
38
+
You can include files in sphinx using the include directive.
39
+
Below is an example of doing this using `myst` syntax.
40
+
````
41
+
```{include} ../README.md
42
+
```
43
+
````
44
+
`````
45
+
46
+
## Documentation tutorials
47
+
48
+
* sphinx gallery vs ()
49
+
* best practices...
43
50
44
51
## API's and Docstrings
45
52
@@ -74,90 +81,6 @@ Example API Documentation (Documentation for all functions and classes in a pack
74
81
```
75
82
76
83
77
-
### What tools to use to build your documentation: sphinx
78
-
79
-
Most python packages use [sphinx](https://www.sphinx-doc.org/) to build their documentation.
80
-
Sphinx has documentation themes that are easy to apply and help you quickly and easily build an easy-to navigate website.
81
-
82
-
Sphinx also offers extensions that support:
83
-
84
-
*[automatically documenting your API using docstrings in your code](https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html)
85
-
*[running and testing code examples in your docstrings (doctest)](https://www.sphinx-doc.org/en/master/usage/extensions/doctest.html)
86
-
87
-
While you are free to use whatever sphinx theme you prefer,
88
-
the most common modern templates that recommend for the Python scientific
All of the above themes support [myst](https://myst-parser.readthedocs.io/)
96
-
which allows you to build your package documentation in using `markdown`
97
-
rather than `.rst`. More on that below.
98
-
99
-
```{tip}
100
-
This book is created using sphinx and the `furo` theme.
101
-
```
102
-
103
-
### myST vs rst syntax to create your docs
104
-
There are two commonly used syntaxes for creating docs:
105
-
106
-
1.[myST:](https://myst-parser.readthedocs.io/en/latest/intro.html) myST is a fusion of markdown and rST. It is a nice option if you are more comfortable writing markdown. But more flexible than markdown.
107
-
2.[rST:](https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html) this is the native syntax that sphinx supports.
108
-
109
-
Markdown is often a preferred syntax to use because:
110
-
111
-
* It is often thought to be simpler and thus easier to learn;
112
-
* Most of your core python package text files, such as your README.md file, are already in `.md` format
113
-
*`GitHub` and `Jupyter Notebooks` support this default text file format.
114
-
115
-
There is no wrong or right when choosing a syntax to write your documentation.
116
-
Choose whichever syntax works best for you and your community!
117
-
118
-
```{tip}
119
-
If you are on the fence about myST vs rst, you might find that *myST* is easier
120
-
for more people to contribute to.
121
-
```
122
-
123
-
### How to host your Python package documentation
124
-
125
-
We suggest that you setup a website to host your documentation. There are two
126
-
ways to do quickly create a documentation website:
127
-
128
-
1. You can host your documentation yourself using [GitHub Pages](https://pages.github.com/) or another online hosting service.
129
-
2. You can host your documentation using [Read the Docs](https://readthedocs.org/).
130
-
131
-
If you don't want to maintain a documentation website for your Python package,
132
-
we suggest using Read the Docs. Read the Docs allows you to:
133
-
134
-
* Quickly launch a website using the documentation found in your GitHub repository.
135
-
* Track versions of your documentation as you release updates.
136
-
137
-
138
-
139
-
## Documentation landing page best practices
140
-
141
-
To make it easy for users to find what they need quickly, all packages should
142
-
have 4 elements on the home page of their documentation:
143
-
144
-
***Getting started:** This section should provide the user with a quick start for installing your package. A small example of how to use the package is good to have here as well.
145
-
***About:** Describe your project, state project goals and what it does.
146
-
***Community:** Instructions for how to help and/or get involved. This section might include a development guide.
147
-
***Documentation:** The actual project documentation. You may have two sections of documentation - the user facing documentation and your API reference.
148
-
149
-
NOTE: in many cases you can include your **README** file and your **CONTRIBUTING** files
150
-
in your documentation given those files may have some of the components listed above.
151
-
152
-
`````{tip}
153
-
You can include files in sphinx using the include directive.
154
-
Below is an example of doing this using `myst` syntax.
155
-
````
156
-
```{include} ../README.md
157
-
```
158
-
````
159
-
`````
160
-
161
84
## Python package API documentation
162
85
163
86
API documentation refers to explanation about the function, inputs and outputs
@@ -168,37 +91,50 @@ in python requires that you use a docstring for each class, function or method t
168
91
* Explains what every input and output variable's (type) is (ie. `string`, `int`, `np.array`)
169
92
* Explains the expected output `return` of the object, method or function.
170
93
171
-
### Python docstring format best-practices
94
+
### Python docstring bestpractices
172
95
173
96
There are several Python docstring formats that you can chose to use when documenting
174
-
your package. We suggest using [numpy-style docstrings](https://numpydoc.readthedocs.io/en/latest/format.html#docstring-standard).
<!-- https://peps.python.org/pep-0287/ - 2002 pep 287-->
104
+
We suggest using [NumPy-style docstrings](https://numpydoc.readthedocs.io/en/latest/format.html#docstring-standard) for your
105
+
Python documentation because:
106
+
107
+
* NumPy style docstrings are human readable (unlike reST which is harder to quickly scan and takes up more lines of code in your modules)
108
+
* NumPy format docstrings are core to the scientific Python ecosystem and defined in the [NumPy style guide](https://numpydoc.readthedocs.io/en/latest/format.html). Thus you will find them widely used there.
175
109
176
110
```{tip}
177
-
If you are using `numpy-style` docstrings, be sure to include the sphinx napoleon
178
-
extension in your documentation `conf.py` file. This extension allows sphinx
179
-
to properly read and format numpy-style docstrings.
111
+
If you are using `NumPy format` docstrings, be sure to include the [sphinx napoleon
112
+
extension](https://www.sphinx-doc.org/en/master/usage/extensions/napoleon.html) in your documentation `conf.py` file. This extension allows sphinx
113
+
to properly read and format NumPy format docstrings.
180
114
```
181
115
182
116
### Docstring examples Better and Best
183
117
184
-
Below is a good example of a well documented function. Notice that this function's
185
-
docstring includes all parameter inputs and outputs. The description of the function
186
-
is short and to the point (2 to 3 sentences). And the return of the function is
187
-
specified.
118
+
Below is a good example of a well documented function. Notice that this
119
+
function's docstring describes every function inputs and the function's output
120
+
(or return value). The description of the function is short and to the point
121
+
(2 to 3 sentences). And the return of the function is specified.
188
122
189
123
```Python
190
124
defextent_to_json(ext_obj):
191
125
"""Convert bounds to a shapely geojson like spatial object.
192
126
This format is what shapely uses. The output object can be used
193
127
to crop a raster image.
128
+
194
129
Parameters
195
130
----------
196
-
ext_obj: list or geopandas geodataframe
197
-
If provided with a geopandas geodataframe, the extent
131
+
ext_obj: list or geopandas.GeoDataFrame
132
+
If provided with a geopandas.GeoDataFrame, the extent
198
133
will be generated from that. Otherwise, extent values
199
134
should be in the order: minx, miny, maxx, maxy.
200
-
Return
201
-
------
135
+
136
+
Returns
137
+
-------
202
138
extent_json: A GeoJSON style dictionary of corner coordinates
203
139
for the extent
204
140
A GeoJSON style dictionary of corner coordinates representing
@@ -245,11 +181,9 @@ def extent_to_json(ext_obj):
245
181
name: directive-fig
246
182
width: 80%
247
183
---
248
-
Using the above numpy-style docstring in sphinx, the autodoc extension will
184
+
Using the above NumPy format docstring in sphinx, the autodoc extension will
249
185
create the about documentation section for the `extent_to_json` function. The
250
186
output of the `es.extent_to_json(rmnp)` command can even be tested using
251
187
doctest adding another quality check to your package.
0 commit comments