Exercises (documentation lesson)¶
Before you start¶
- Discuss the exercise idea with the classroom.
- Distribute exercises among groups of 2-3 persons.
- Open a GitHub issue and inform the community about the problem and how you plan to solve it. Discuss why we do this.
- Fork this project.
- Commit to your fork. In your commit message auto-close the issue you have addressed.
- Submit a pull request.
- We then review the pull requests.
- After the pull requests are merged we verify that documentation updates itself.
Basic¶
- Document the purpose of this example code.
- Document how to clone the code.
- Describe the project tree structure.
- Write a sentence or two about Zipf’s law and link to Wikipedia (coordinate with the group working on the previous exercise).
- Document how to check the code style with
pycodestyle
. - Give other developers hints on how they can contribute to the documentation.
- Document how to build the documentation locally (coordinate with the group working on the previous exercise).
- Add an example output.
- Add an example plot (coordinate with the group working on the previous exercise).
- Document where/how to ask for help.
- Add a math equation somewhere.
Advanced¶
- Add a test and document how to run it.
- Add the possibility to auto-document Python code.
Meta¶
- Add new exercises ideas for future workshops (edit this file).