docs: Doctest-able Examples

[johnandersen777]

DFFML is hoping to participate in Google Summer of Code (GSoC) under the Python Software Foundation umbrella. You can read all about what this means at http://python-gsoc.org/. This issue, and any others tagged gsoc and project are not general bugs, but project ideas which one could choose to write a proposal for. Issue tagged as gsoc and project can also be used as an example for what the scope of an idea for a project proposal might look like.

Project Idea: Doctest-able Examples

Project description:
We have a lot of tests, and a lot of command line usage examples. However, we don't have a lot of examples of how to use the plethora of classes, methods, and functions that are provided. The goal of this project is to create code examples for as much of the codebase as possible. We recently switched over numpy style docstrings. So adding information on the arguments, parameters, and return values of things would also be good, but is not a must for this project. The goal is to have working examples that can be tested via the sphinx doctest plugin. This will make it so that users can look at the docs for anything the github pages site, copy paste it into a Python file and it'll work (since the examples you write will be tested on every CI run).

Skills: Python, git
Difficulty level: Intermediate

Related Readings/Links:

• https://www.sphinx-doc.org/en/master/usage/extensions/doctest.html
• docs: Woefully inadequate docstrings #336
• docs: Everything needs doctestable examples #345

Potential mentors: @pdxjohnny, @sudharsana-kjl

Getting Started:
The tests have most of the code you'll need, you'll just need to adapt it from test code into example code.

A good first target would be the functions under the High Level API Docs as you can reference the quickstart guide for their usage.

The scripts/doctest.sh can be used to run the doctests.

What we want to see in your application:
Describe how you intend to solve the problem, and give us some "stretch goals", for example define some percentage of functions with testable examples as "success", and some percentage as "exceeds".

[mhash1m]

Hi,

Since Python Software Foundation umbrella has been accepted into GSOC, does that mean dffml has also been accepted? I'm interested in applying for this project so had to ask. :)

[johnandersen777]

@mhash1m Yes!

[johnandersen777]

@mhash1m @kurianbenoy I've enabled the doctests in the CI and updated the issue with how to run the doctests.

[mhash1m]

@pdxjohnny Thanks, I'll dive into it.

[Byambaa0325]

Hi @pdxjohnny , is this project still taking applications? I would like to take on it.

[johnandersen777]

@Byambaa0325 With regards to GSoC all projects are open to anyone to submit a proposal. Once chosen proposals are announced, then it's only one per person. Applications are open until the 31st.