search

intel / dffml

The easiest way to use Machine Learning. Mix and match underlying ML libraries and data set sources. Generate new datasets or modify existing ones with ease.
https://intel.github.io/dffml/main/
MIT License
251 stars 138 forks source link

docs: Doctest-able Examples #366

Open pdxjohnny opened 4 years ago

pdxjohnny commented 4 years ago

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:

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 commented 4 years ago

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. :)

pdxjohnny commented 4 years ago

@mHash1m Yes!

pdxjohnny commented 4 years ago

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

mhash1m commented 4 years ago

@pdxjohnny Thanks, I'll dive into it.

Byambaa0325 commented 4 years ago

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

pdxjohnny commented 4 years ago

@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.