Skip to content

Contribute to the documentation

Extending the documentation

  • Familiarize yourself with how the documentation is organized and determine were your contribution will go.
  • Add docstrings to your code
  • Add / update markdown files in the docs/ subfolders, including making references to docstrings using the ::: characters.
  • Reference your new files in mkdocs.yml
  • Inspect the result by render the documentation site on localhost
$ mkdocs serve
  • Commit your work and open a PR.

For further info see: https://www.mkdocs.org/

Organization of the documentation

The documentation follows the best practice for project documentation as described by Daniele Procida in the Diátaxis documentation framework and consists of four separate parts:

Tutorials

This part of the project documentation focuses on a learning-oriented approach. You'll learn how to get started with the code in this project. - Help newcomers with getting started - Teach readers about your library by making them write code - Inspire confidence through examples that work for everyone, repeatably - Give readers an immediate sense of achievement - Show concrete examples, no abstractions - Provide the minimum necessary explanation - Avoid any distractions

How-To Guides

This part of the project documentation focuses on a problem-oriented approach. You'll tackle common tasks that you might have, with the help of the code provided in this project.

Explanation

This part of the project documentation focuses on an understanding-oriented approach. You'll get a chance to read about the background of the project, as well as reasoning about how it was implemented.

  • Give context and background on your library
  • Explain why you created it
  • Prodive details of the analytical methodologies
  • Provide multiple examples and approaches of how to work with it
  • Help the reader make connections

Reference

This part of the project documentation focuses on an information-oriented approach. Use it as a reference for the technical implementation of the package code. Documentation can automatically populatedfrom module and function docstrings.