Python Documentation Testing: A Hands-on Tutorial#
Welcome to our repository!
While the name may suggest it’s all about Python tutorials, that’s not our main goal.
The motivation to start this project wasn’t to create Python tutorials but rather to demonstrate how to create well-structured, well-documented, and well-tested Python documentation using powerful tools such as MyST, MyST-NB, Jupytext, and Sphinx.
Modern development practices emphasize not just writing code but also ensuring its maintainability, and documentation plays a pivotal role in this. Good documentation helps users and contributors understand the purpose of your project, its architecture, how to use it, and how to contribute.
However, writing effective documentation isn’t as simple as typing a bunch of words and hoping they make sense. It involves structuring it properly so that users can find what they need, testing it to ensure it’s correct and stays correct as the project evolves, and using the right tools to automate these processes as much as possible.
In this repository, you’ll find a series of “Python tutorials”. But their real purpose is to serve as examples of how to write, structure, test, and build your Python project’s documentation. These tutorials demonstrate best practices in writing documentation, such as:
Structuring your documentation with MyST and Sphinx for easy navigation and readability.
Writing your documentation as Jupyter notebooks and converting them to MyST markdown with Jupytext, so you can version control them effectively.
Testing your code snippets in the documentation to ensure they work as expected.
Building your documentation into a static website with Sphinx.
By following these practices, you’ll be able to create Python documentation that is easy to understand, maintain, and contribute to. We hope you find this project helpful in your documentation journey!