Provide guidance about examples that demonstrate how to use a package

[wigging]

I don't see much information in this package development guide regarding examples for a package. Well written Python packages provide examples on how to use that package. Those examples can be in docstrings of the code which are rendered by Sphinx for documentation. Examples can also be executable Python scripts or Jupyter notebooks which are typically located in the root directory of the project or as an external repository. Providing some guidance on how developers of Python packages can provide examples to their users should be included in this package development guide.

[lwasser]

hey there @wigging 👋 i have missed so many notifications in this repo - my apologies. i've (hopefully) fixed. my notifications so i see these in the future. I agree that having some examples of how to add examples (and even test them) would be wonderful. is this something that you are interested in helping with by chance?

SO SO sorry i completely missed this issue.

[wigging]

@lwasser I can help with this issue but I have not found a good approach on how to actually test examples. My suggestion would be to use pytest to at least verify that the examples successfully execute. Do you or someone else you know have experience with testing examples?

[lwasser]

i just dug a bit more into our guide. We do have this section in the guide

what are you thinking in terms of adding to what we have? are you thinking about content that expands upon ways to include examples like:

• docstring examples w doctest to test those examples
• sphinx gallery allows you to run example tutorials in your docs to ensure they build (sphinx specific however!)
• etc

OR:

• is our organization such that it's easy to miss this section?
• are you thinking about something that is a bit more tutorial like?

i just want to ensure we are on the same page here before moving forward!! i forgot we already had added doctest. But there is always an opportunity to improve on our content!! Many thanks!

[wigging]

That link is about examples in docstrings which can be run and tested using doctest. But I don't see anything in the guide about standalone examples such as scripts (example.py) or notebooks (example.ipynb) that users can run. These standalone examples are usually provided in an examples directory. Is there anything in the guide about these types of examples?

[lwasser]

oh perfect - i'm glad we clarified here.

we have this page - https://www.pyopensci.org/python-package-guide/documentation/write-user-documentation/create-package-tutorials.html which is about tutorials but it's really more about infrastructure to publish the tutorials.

There is likely an opportunity here to split out infrastructure to create the package from the actual example content.

have a look and let me know what you think.

[wigging]

@lwasser Ok, that page talks about creating documentation of examples. I guess I was confused by the title "Create Package Tutorials" which made me think it was a tutorial about creating a Python package. Anyway, this can be closed unless you have more comments.