Skip to content

Documentation#

Documentation is anything about your project that is not executed or used by your application or development environment.

While code is written for both humans and machines, documentation is purely written for other humans.

Each project starts with a README and CHANGELOG file. Additional documentation, such as a user guide or reference documentation is usually written in Markdown and published using one of the documentation tools included with the template.

README#

The README included with the template only covers the bare minimum (installation, basic usage).

README.md 
# Sample Project

[![badge_documentation][]][documentation] [![badge_pipeline][]][pipeline] [![badge_coverage][]][coverage] [![badge_maintainability][]]()

[documentation]: https://mkj.github.io/sample-project
[badge_documentation]: https://img.shields.io/badge/Documentation-main-blue
[coverage]: https://mkj.github.io/sample-project/coverage
[badge_coverage]: https://mkj.github.io/sample-project/badges/coverage.svg
[badge_pipeline]: https://github.com/mkj/sample-project/actions/workflows/ci.yaml/badge.svg
[pipeline]: https://github.com/mkj/sample-project/actions?query=branch%3Amain
[badge_maintainability]: https://mkj.github.io/sample-project/badges/maintainability.svg

<!-- TODO: extend readme template -->

## Installation

'''console
pip install git+https://github.com/mkj/sample-project
'''

## Usage

Call the `sample-project` command line interface like this:

'''console
$ sample-project
Hello, Sample Project!
'''

Provide the `--help` option to see supported options and arguments.

---
*This project was created using the [Project Template for Python](https://github.com/jannismain/python-project-template)*

For additional sections often found in READMEs, see Make a README, this README Generator or explore READMEs of popular GitHub projects.

CHANGELOG#

The CHANGELOG included with the template follows the keep a changelog format.

CHANGELOG.md 
# Changelog

All notable changes to this project will be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [Unreleased]

### Added

### Fixed

### Changed

### Removed

## [0.0.1] - 2000-01-01

Initial Release

[unreleased]: https://github.com/mkj/sample-project/compare/v0.0.1...HEAD
[0.0.1]: https://github.com/mkj/sample-project/releases/tag/v0.0.1

API Documentation#

Part of the reference documentation is a section on the API1 provided by your Python package or module. While this can be hand-written, it would be hard to keep in sync with the actual implementation. Therefore, it is usually included as docstrings with the code and extracted by a third-party tool.

Documentation Tools#

Material for MkDocs#

Projects generated with this option start with MkDocs as a documentation system right out of the box, which is configured via the ./mkdocs.yaml file to use the excellent Material for MkDocs theme. Python docstrings are extracted and added as reference documentation using the mkdocstrings extension.

See the MkDocs reference for more information about the MkDocs configuration provided by the template.

Sphinx#

Projects generated with this option start with Sphinx as a documentation system right out of the box, which is configured via the ./conf.py file to use the excellent Furo theme. myst is included to add support for Markdown. Python docstrings are extracted and added as reference documentation using the .. automodule directive.

See the Sphinx reference for more information about the Sphinx configuration provided by the template.

  1. For Python projects, the API includes classes and methods meant to be used by users or programs interacting with your code. ↩