A minimal Python project template built with Poetry.
Project description
Minimal working example of a packaged Python project. Key integrations include:
- Build System (Poetry).
- Test Framework (PyTest).
- Auto-docs with Markdown and ReST support (pdoc).
- CI/CD (GitHub Actions).
Contents
Structure
Documentation is generated from Python docstrings and takes a structure mirroring that of the source code (API documentation).
Initial focus could be on high-level (public) APIs intended for direct use by end-users.
Developers can thus grow the documentation organically within a single task-based workflow. As soon as a new feature/function is added - the developer need only include a docstring in their commit and it will reflect in the hosted page.
Markdown and ReST support
The pdoc
framework renders Markdown in docstrings to HTML:
- Lists
- Are
- Supported
As are code blocks:
# Example invocation
result: Type = function(param="value", *variadic_args, **variadic_kwargs)
Data models
The pydantic
framework has quickly become the leading
data validation library for Python.
It's not a stretch to say that there's a whole ecosystem being built around it with everything from web frameworks to data science toolkits using it as the base for their data models.
From a documentation perspective, if you can describe your data source as a pydantic
derived
data model and then group them accordingly
such links could be fronted as data schemas. Standard representations such as "JSON Schema" can
be generated directly from pydantic
models.
This also has advantages for testing.
Advanced tools
The pdoc
framework is arguably the simplest auto-documentation tool for Python.
Below are some more advanced tools that are popular with large open-source projects:
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.