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
+51-43
Original file line number
Diff line number
Diff line change
@@ -1,4 +1,4 @@
1
-
# Documentation for your Open Source Python Package: An Overview
1
+
# Documentation for your Open Source Python Package
2
2
3
3
```{important}
4
4
Please note that the tools discussed here are those that
@@ -37,7 +37,7 @@ detail about creating each of the above elements. We also suggest
37
37
tools that will help you build your documentation.
38
38
``` -->
39
39
40
-
## Documentation is critical to the success of your Python open source package
40
+
## Documentation is critical for your Python package's success
41
41
42
42
Documentation is as important to the success of your Python open source package
43
43
as the code itself.
@@ -51,41 +51,77 @@ to build a base of contributors to your package.
51
51
## Two types of Python package users
52
52
53
53
The documentation that you write for your
54
-
package should target a two types of users:
54
+
package should target two types of users:
55
55
56
56
### 1. Basic Tool Users
57
57
58
-
There are people who will use your code in their Python workflows. They might be new(er) to Python and/or data science. Or expert programmers. They need to known
58
+
Basic tool users are the people who will use your package code in their
59
+
Python workflows. They might be new(er) to Python and/or data science. Or
60
+
expert programmers. But they might not have a background in software
61
+
development. These users need to know:
62
+
59
63
* How to install your package
60
-
*And dependencies it requires to run the code in your package (for instance perhaps a tool like GDAL needs to be installed on a machine first)
64
+
*How to install dependencies that your package requires
61
65
* How to get started using the code base
62
-
* Information on how to cite your code / give you credit if they are using it in a research application.
63
-
* Information on the license that your code uses so they know how they can or can't use the code in an operational setting that may include money exchanges.
66
+
* Information on how to cite your code / give you credit if they are using it
67
+
in a research application.
68
+
* Information on the license that your code uses so they know how they can
69
+
or can't use the code in an operational setting.
64
70
65
71
### 2. Potential tool contributors
66
72
67
-
The other subset of users are more experienced using Python or developing tools. Potential contributors are likely using your tool. But they also might contribute bug fixes or updates to your documentation. They need all of the things that a basic user needs. But, they also need direction in terms of how you'd like for them to contribute to your package. These potential contributors need:
73
+
The other subset of users are more experienced and/or more engaged
74
+
with your package. As such they are
75
+
potential contributors. These users:
76
+
77
+
* might have a software development background,
78
+
* might also be able to contribute bug fixes to your package or updates to your documentation
79
+
* might also just be users who will find spelling errors in your documentation, or bugs in your tutorials.
80
+
81
+
These users need all of the things that a basic user needs. But, they
82
+
also need to understand how you'd like for them to contribute to your
83
+
package. These potential contributors need:
68
84
69
85
* A development guide to help them understand the infrastructure used in your package repository.
70
86
* Contributing guidelines that clarify the types of contributions that you welcome and how you'd prefer those contributions to be submitted.
71
87
88
+
```{important}
89
+
It's important to remember that the definition of what a contribution is can be
90
+
broad. A contribution could be something as simple as a bug report. Or fixing a
91
+
spelling issue in your documentation. Or it could be a code fix that includes a
92
+
new test that covers an edge-case that they discovered.
93
+
```
94
+
95
+
96
+
## Documentation elements that pyOpenSci looks for reviewing a Python package
72
97
73
-
## Documentation elements that pyOpenSci looks for when reviewing a Python package
98
+
In the pyOpenSci open peer review, we look for
99
+
a documentation structure that supports both your tool users and potential
100
+
contributors. The files and elements that we look for specifically can be
101
+
found in our peer review check list (see link below).
74
102
75
-
In the pyOpenSci open peer review process, we look for
76
-
a documentation structure that suypports both your tool users and potential contributors. The files and elements that we
77
-
look for are listed below.
103
+
In this guide, we discuss each required element, and also discuss other elements
104
+
that you should consider in your package's documentation in more detail.
78
105
106
+
<!-- TODO: EIC checks are missing: code of conduct -->
1. Individual files in your GitHub (or GitLab) repository including:
80
116
* [A clear and to the point **README.md** file](readme-file-best-practices) that includes information about how to cite your package.
81
117
* A [**CONTRIBUTING.md** file](contributing-license-coc) 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.
82
-
* A [**CODE_OF_CONDUCT.md**](contributing-license-coc.html#the-code-of-conduct-md-file) file. This file sets up the guidelines for how your community interacts. It ideally ensures that everyone feels safe and can report inappropriate behavior if need be. <!--<not sure why header targets aren't working here with Sphinx they work online> -->
118
+
* A [**CODE_OF_CONDUCT.md**](contributing-license-coc.html#the-code-of-conduct-md-file) file. This file sets up the guidelines for how your community interacts. It ideally ensures that everyone feels safe and can report inappropriate behavior if need be.
83
119
* [**A LICENSE.txt file**](contributing-license-coc.html#your-repository-should-have-a-license-md-file) A license file declaring the OSI-approved license that you select and instructions for citing your package.
84
-
* We also suggest (but don't require) that you include a development guide that details the infrastructure used in your package. Sometimes this file is included in the user-facing documentation website (discussed below).
120
+
* We also suggest (but don't require) that you include a development guide that details the infrastructure used in your package. Sometimes this file is included in the user-facing documentation website (discussed below).
85
121
1. [**User focused package documentation**](package-documentation-best-practices) that helps users understand how to install, setup and use your package. Documentation is most often contained in a stand-alone website. The user-focused documentation should include:
86
122
* **Tutorials and quick start code examples** that help a user get started using your package.
87
123
* **Documentation for user-facing functions, objects and methods in your package (the API).** 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.
An example from the MovingPandas GitHub repository with all of the major files in it including CONTRIBUTING.md, README.md, CODE_OF_CONDUCT.md and a LICENSE.txt file. *(screen shot taken Nov 23 2022)*
98
134
```
99
135
100
-
The files mentions above (README, Code of Conduct, license
101
-
file, etc) are used as a measure of package community health
102
-
on many online platforms. Below, you can see the community
103
-
standards page that everyone has in their GitHub repository.
alt: Image showing that the MovingPandas GitHub repository community health page with green checks next to each file including: description, README, code of conduct, contributing, license and issue templates. Note that Security policy has a yellow circle next to it as that is missing from the repo.
110
-
---
111
-
GitHub community health looks for a readme file among other elements when it evaluates the community level health of your repository. This example is from the [MovingPandas GitHub repo](https://github.com/anitagraser/movingpandas/community) *(screen shot taken Nov 23 2022)*
112
-
```
113
-
114
-
[Snyk](https://snyk.io/advisor/python) is another well-known company that keeps tabs on package health.
115
-
Below you can see a similar evaluation of files in the Github repo as a
alt: Screenshot of the Snyk page for movingpandas. It shows that the repository has a README file, contributing file, code of conduct. It also shows that it has 30 contributors and no funding. The package health score is 78/100.
123
-
---
124
-
Screenshot showing [SNYK](https://snyk.io/advisor/python/movingpandas) package health for moving pandas. Notice both platforms look for a README file. *(screen shot taken Nov 23 2022)*
125
-
```
126
136
127
137
128
138
## What's next in this Python package documentation section?
@@ -133,8 +143,6 @@ documentation for your Python package. We will also suggest
133
143
tools that you can use to build your user-facing documentation website.
134
144
135
145
136
-
137
-
138
146
<!--
139
147
Commenting this out for now - it will be moved to another section
alt: Image showing that the MovingPandas GitHub repository community health page with green checks next to each file including a description, README, code of conduct, contributing, license and issue templates. Note that Security policy has a yellow circle next to it as that is missing from the repo.
29
+
---
30
+
GitHub community health looks for a readme file among other elements when it evaluates the community level health of your repository. This example is from the [MovingPandas GitHub repo](https://github.com/anitagraser/movingpandas/community) *(screen shot taken Nov 23 2022)*
31
+
```
32
+
33
+
[Snyk](https://snyk.io/advisor/python) is another well-known company that
34
+
keeps tabs on package health. Below you can see a similar evaluation of files
35
+
in the Github repo as a measure of community health.
alt: Screenshot of the Snyk page for movingpandas. It shows that the repository has a README file, contributing file, code of conduct. It also shows that it has 30 contributors and no funding. The package health score is 78/100.
42
+
---
43
+
Screenshot showing [SNYK](https://snyk.io/advisor/python/movingpandas) package health for moving pandas. Notice both platforms look for a README file. *(screen shot taken Nov 23 2022)*
0 commit comments