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

1. 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 shoud 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
• Example review comment
• Discourse discussion on Good, Better, Best

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.