DocInit
DocInit is an opiniated, yet flexible documentation generator for your Python projects. It removes the burden of rewriting the same configuration files over and over, and instead favors a simple, non-repetitive declarative style. It uses Sphinx and Sphinx AutoAPI behind the scenes.
Features
Entirely configurable from your setup.cfg file
Automatically fills the blanks so you don’t have to repeat yourself
Allows master and sub projects
Compatible with Read the Docs
Flexible and extensible
Example
The Timeflux documentation is managed by DocInit.
Install
pip install docinitUsage
Write your documentation
Or not. If you don’t do anything, DocInit will automatically find your packages, generate API documentation, and create an index page (using either your repo’s README.rst file or a default paragraph).
You can add your own .rst files in the doc directory, and overwrite the default index.rst. Put your logo and favicon in doc/_static/logo.png and doc/_static/favicon.ico, respectively.
If you need to configure further, do it in the docinit section of your setup.cfg. Refer to the Configuration section for details.
Setup a Sphinx project
The following will take care of initializing everything:
python setup.py docinitIf you don’t have a setup.py file, you can instead simply run:
docinitDon’t worry, nothing will be overwritten if a file with the same name already exists. There is no need to re-run this command, even if you modify your setup.cfg. But if you do, nothing bad will happen.
You don’t have to commit the generated files. Refer to the Read the Docs section to learn how to setup your project at build time.
Build
cd doc
make htmlYou can now find your generated documentation in doc/_build/html/.
By default, the make command will return an error (but will still build everything) in case of warning. This allows for easy integration in your CI/CD pipelines.
Configuration
The following options are accepted:
Key |
Type |
|---|---|
doc_dir |
str |
name |
str |
parent_url |
str |
logo_url |
str |
favicon_url |
str |
version |
str |
release |
str |
packages |
list |
author |
str |
copyright |
str |
analytics |
str |
canonical_url |
str |
There is no required option. If not set, DocInit will try to find an appropriate value elsewhere. If it fails, it will settle on a default value.
doc_dir
This is where your documentation lives.
Default |
Lookups |
|---|---|
doc |
|
name
The name of your project.
Default |
Lookups |
|---|---|
Project |
|
parent_url
If you are managing a subproject, this is the URL of the main project. When set, DocInit adds a Back entry in the menu, and configures the intersphinx mapping.
Default |
Lookups |
|---|---|
None |
logo_url
The URL of an image that will be downloaded to doc/_static/logo.png. Useful for subprojects.
Default |
Lookups |
|---|---|
None |
favicon_url
The URL of an image that will be downloaded to doc/_static/favicon.ico. Useful for subprojects.
Default |
Lookups |
|---|---|
None |
version
The semantic version of your package. If it is not explicitly defined, DocInit will use setuptools_scm to fetch it from git tags, or fallback to 0.0.0.
Default |
Lookups |
|---|---|
From git tags |
|
release
The full version of your package, including VCS status. If it is not explicitly defined, DocInit will use setuptools_scm to fetch it from git tags, or fallback to 0.0.0.
Default |
Lookups |
|---|---|
From git tags |
|
packages
The list of packages for which the API documentation will be generated. If it is not specified, DocInit will discover packages from the root of your project (where setup.cfg is located).
Default |
Lookups |
|---|---|
find: |
|
copyright
The copyright for this project. If it is not defined, it will be constructed from the year of the first commit, the current year, and author.
Default |
Lookups |
|---|---|
Generated |
|
analytics
Your Google Analytics ID. It should look like UA-XXXXXXX-1.
Default |
Lookups |
|---|---|
None |
canonical_url
If your URL is available through multiple URLs, the canonical url indicates to search engines which one it should index. The URL points to the root path of the documentation and requires a trailing slash.
Default |
Lookups |
|---|---|
None |
Arbitrary options
That is not all: you can pass arbitrary options, and they will be injected in conf.py. For example, setting: autoapi_generate_api_docs = 0 will disable API documentation. Please refer to the official Sphinx and Sphinx AutoAPI documentation for recognized options.
Read the docs
If you decide to not push the files created by DocInit, the easiest way is to install your package before building the docs. You can configure this behavior either in the Advanced settings tab of your dashboard or in your configuration file.
Then you just need to invoke DocInit during the setup process.
This can be achieved in your setup.py:
setup(
...
setup_requires="docinit",
docinit=True,
...
)Or if you prefer, in your pyproject.toml:
[tool.docinit]
[build-system]
requires = ["setuptools>=42", "wheel", "docinit"]
build-backend = "setuptools.build_meta"Please note: before version 20.1.b1 and since version 20.1.1, pip builds in a temporary directory. Therefore, on Read The Docs you need to install the package with setup.py so the documentation is generated in the current directory.
Alternative build systems
DocInit currently only parses Setuptools setup.cfg files. We plan to add support for other build systems as well, such as Flit and Poetry, which rely on pyproject.toml files.
1 maintainer
Metadata
1 maintainer
Release files for docinit 0.19
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| docinit-0.19.tar.gz | 17.4 kB | Without provenance | Details for docinit-0.19.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| docinit-0.19-py3-none-any.whl | Python 3 | none | any | Details for docinit-0.19-py3-none-any.whl |
Total release size: 32.1 kB
Release files / docinit-0.19.tar.gz
| Download URL | docinit-0.19.tar.gz |
|---|---|
| Size | 17.4 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
86a499d2bcd104da550147aece0e4744fb127fd9ef577606a811ee39caca5fb2
|
|
BLAKE2b-256 checksum How to use checksums |
48f339fa052dc16f939794a2d6847174bea4d4e49ec8867dbbba85ef9e64fb14
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/4.0.2 CPython/3.11.3
|
Release files / docinit-0.19-py3-none-any.whl
| Download URL | docinit-0.19-py3-none-any.whl |
|---|---|
| Size | 14.6 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
52868aafb9d2f026dc0222489da395bbe93e322f35df5487344dd85230de8102
|
|
BLAKE2b-256 checksum How to use checksums |
01855e82aa4d7ff939606033ac0c3ed8b755efcdd955fcc9af757cf06937da02
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/4.0.2 CPython/3.11.3
|
Security for docinit 0.19
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.
