Python library template¶
A python library template with a few pre-configured tools.
For the minimimum required changes, copy the folder structure,
edit setup.py for the name of the library,
change the mylib/ folder to the name of the new library and it’s ready.
Preconfigured dev tools:
- Documentation with Sphinx.
- Keep a changelog for Semantic versioning.
- Testing with PyTest
- Autoformatting with Black and isort.
- Code linting with Flake8.
- Documentation linting with Darglint, and pydocstyle.
- Some automation with make and git hooks.
Makefile¶
To manage installation and dev tools,
the template has a Makefile.
(See Make for Windows)
> make help
install Install the library and dependencies
install-dev Install in editable mode with dev. dependencies
test Run pytest
format Run formatting tools
lint Run linters and formatting tools (no edits)
docs Build the docs
Changelog¶
Document changes in changelog.md,
following Keep a changelog
and Semantic versioning.
Documentation¶
The documentation is generated with Sphinx,
configured in docs_src/conf.py, and uses
Sphinx-gallery
to generate notebook-style examples from source code in examples/.
The source of the is in docs_src/
and gets compiled to docs/
with make docs
for easy publication with Github pages.
If you are not using Github pages, you should .gitignore the
documentation output.
A ReadTheDocs config file is also present,
in .readthedocs.yml, if you wish to publish there.
RTD uses its theme by default, whereas a local run of
Sphinx needs to be told to use the ReadTheDocs theme.
To publish on RTD, you need to comment out the following line
in docs_src/conf.py
html_theme = "sphinx_rtd_theme"
Autoformatting¶
The template comes with a configuration of
Black (black.toml) compatible with
isort (.isort.cfg).
Use make format to format the source, or install one of the
editor integration
to have automatic formatting.
Linting¶
Code linting with Flake8 (.flake8),
which includes
PyFlakes (linting)
McCabe (complexity)
and pycodestyle (style).
Documentation linting with
Darglint (linting)
pydocstyle (style).
Run with make lint.
make install-dev installs a git hook to lint before commits.
For examples of the Sphinx-gallery documentation output, see Examples