pyOpenSci Meeting Notes - 28 Feb 2020#
Attendees#
Leah Wasser, Earth Lab, CU Boulder
Jenny Palomino, Earth Lab, CU Boulder
Chris Holdgraf, UC Berkeley
Ivan Ogasawara, Quansight
Discussion Points#
How Much Documentation is “Good Enough” for PyOpenSci?#
How much documentation is enough: dev_guide says “all user facing functions should have documentation with examples”
What is our good enough requirement for documentation
docstrings: do ALL docstrings needs examples even if there is a solid help / gallery.
Current language in our dev guide:
MINIMUM: Some examples of how to use the functions
Better: Docstring generated
Chris will email alison hill (r studio ) who gave a good talk on docs.
Create a little survey on what people expect for documentation?
JOSS REQUIREMENTS
https://joss.readthedocs.io/en/latest/review_criteria.html#example-usage
Maybe we switch to ok, better, best
Documentation#
New language below:
ok (required): all user facing functions (inputs and outputs) are documented both in the code and in the user-facing documentation. better: all user facing functions are documented with examples (in tutorials or doc strings) best: all user facing functions are documented and there is are tutorials (vignettes) that demonstrate example user workflows
README
All packages should have a README.md in their root directory. The README should include, from top to bottom:
The package name
Badges for continuous integration and test coverage, the badge for pyOpenSci peer-review once it has started (see below), a repostatus.org badge, and any other badges. If the README has many more badges, you might want to consider using a table for badges, see this example, that one and that one. Such a table should be more wide than high.
Short description of goals of package, with descriptive links to all vignettes (rendered, i.e. readable, cf the documentation website section) unless the package is small and there’s only one vignette repeating the README.
Installation instructions
Any additional setup required (authentication tokens, etc)
Brief demonstration usage
Direction to more detailed documentation (e.g. your documentation files or website).
If applicable, how the package compares to other similar packages and/or how it relates to other packages
Citation information
Good/Better/Best Recommendations:
Good: README with name, description, installation instructions, and direction to further documentation.
Better/Best: All the above plus usage examples, citation information, and CI and/or test coverage badges.
Documentation
All external package functions, classes, and methods should be fully documented with examples.
Good/Better/Best:
Good: Manually updated documentation as text files that ship with your package.
Better: A documentation website using Sphinx to convert rst files to HTML and Read the Docs to host your site.
Best (optional): Also consider automatically generated documentation from docstrings using autodoc
https://www.pyopensci.org/dev_guide/packaging/packaging_guide#Documentation
Reviews#
one created a google doc. i can see why this is useful but i may need to copy some of it into the issue just in case that doc ever disappears. in the future as the editor i should make sure that the text is in the issue itself.
Similarly, Testing - What if Tests Are Failing?#
maybe this is a space for community feedback as well? what if tests fail? How much do we want to enforce test integrity?
expected to fail tests
Meeting time#
Earlier is better in the day.