|Build| |PyPI|
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 <https://www.sphinx-doc.org/>`__ and `Sphinx AutoAPI <https://github.com/readthedocs/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 <https://readthedocs.org/>`__
- Flexible and extensible
Example
-------
The `Timeflux documentation <https://doc.timeflux.io>`__ is managed by DocInit.
Install
-------
.. code::
pip install docinit
Usage
-----
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 <https://setuptools.readthedocs.io/en/latest/setuptools.html#configuring-setup-using-setup-cfg-files>`__. Refer to the `Configuration`_ section for details.
Setup a Sphinx project
~~~~~~~~~~~~~~~~~~~~~~
The following will take care of initializing everything:
.. code::
python setup.py docinit
If you don't have a `setup.py` file, you can instead simply run:
.. code::
docinit
Don'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
~~~~~
.. code::
cd doc
make html
You 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`` - ``source-dir`` in the ``build_sphinx`` section
======= =======
name
~~~~
The name of your project.
=========== =======
Default Lookups
=========== =======
``Project`` - ``project`` in the ``build_sphinx`` section
- ``name`` in the ``metadata`` section
- name of the current git repo
=========== =======
parent_url
~~~~~~~~~~
If you are managing a `subproject <https://docs.readthedocs.io/en/stable/subprojects.html>`__, this is the URL of the main project. When set, DocInit adds a `Back` entry in the menu, and configures the `intersphinx mapping <https://www.sphinx-doc.org/en/master/usage/extensions/intersphinx.html>`__.
======== =======
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 <https://semver.org/>`__ of your package. If it is not explicitly defined, DocInit will use `setuptools_scm <https://github.com/pypa/setuptools_scm>`__ to fetch it from git tags, or fallback to ``0.0.0``.
============== =======
Default Lookups
============== =======
From git tags - ``version`` in the ``build_sphinx`` section
- ``version`` in the ``metadata`` section
============== =======
release
~~~~~~~
The full version of your package, including VCS status. If it is not explicitly defined, DocInit will use `setuptools_scm <https://github.com/pypa/setuptools_scm>`__ to fetch it from git tags, or fallback to ``0.0.0``.
============== =======
Default Lookups
============== =======
From git tags - ``release`` in the ``build_sphinx`` section
============== =======
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:`` - ``packages`` in the ``options`` section
========= =======
author
~~~~~~
The author of the project.
============= =======
Default Lookups
============= =======
``Anonymous`` - ``author`` in the ``metadata`` section
- From the first commit in the current git repository
============= =======
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 - ``copyright`` in the ``build_sphinx`` section
========== =======
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 <https://www.sphinx-doc.org/en/master/usage/configuration.html>`__ and `Sphinx AutoAPI <https://sphinx-autoapi.readthedocs.io/en/latest/reference/config.html>`__ 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 <https://docs.readthedocs.io/en/stable/config-file/v2.html#packages>`__.
Then you just need to invoke DocInit during the setup process.
This can be achieved in your `setup.py`:
.. code:: python
setup(
...
setup_requires="docinit",
docinit=True,
...
)
Or if you prefer, in your `pyproject.toml`:
.. code:: 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 <https://pip.pypa.io/en/stable/news/>`__. 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 <https://flit.readthedocs.io/>`__ and `Poetry <https://python-poetry.org/>`__, which rely on `pyproject.toml` files.
.. |Build| image:: https://github.com/mesca/docinit/workflows/Python%20application/badge.svg
.. |PyPI| image:: https://badge.fury.io/py/docinit.svg
Raw data
{
"_id": null,
"home_page": "https://github.com/timeflux/docinit",
"name": "docinit",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "doc,autodoc,sphinx,apidoc",
"author": "Pierre Clisson",
"author_email": "contact@timeflux.io",
"download_url": "https://files.pythonhosted.org/packages/d6/90/98921b4042df758fe0129422c002748af69fe513c0b6a2d3ad324174f73e/docinit-0.18.tar.gz",
"platform": null,
"description": "|Build| |PyPI|\n\nDocInit\n=======\n\nDocInit is an opiniated, yet flexible documentation generator for your Python projects.\nIt removes the burden of rewriting the same configuration files over and over, and instead favors a simple, non-repetitive declarative style. It uses `Sphinx <https://www.sphinx-doc.org/>`__ and `Sphinx AutoAPI <https://github.com/readthedocs/sphinx-autoapi>`__ behind the scenes.\n\nFeatures\n--------\n\n- Entirely configurable from your `setup.cfg` file\n- Automatically fills the blanks so you don't have to repeat yourself\n- Allows master and sub projects\n- Compatible with `Read the Docs <https://readthedocs.org/>`__\n- Flexible and extensible\n\nExample\n-------\n\nThe `Timeflux documentation <https://doc.timeflux.io>`__ is managed by DocInit.\n\nInstall\n-------\n\n.. code::\n\n pip install docinit\n\nUsage\n-----\n\nWrite your documentation\n~~~~~~~~~~~~~~~~~~~~~~~~\n\nOr 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).\n\nYou 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.\n\nIf you need to configure further, do it in the ``docinit`` section of your `setup.cfg <https://setuptools.readthedocs.io/en/latest/setuptools.html#configuring-setup-using-setup-cfg-files>`__. Refer to the `Configuration`_ section for details.\n\nSetup a Sphinx project\n~~~~~~~~~~~~~~~~~~~~~~\n\nThe following will take care of initializing everything:\n\n.. code::\n\n python setup.py docinit\n\nIf you don't have a `setup.py` file, you can instead simply run:\n\n.. code::\n\n docinit\n\nDon'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.\n\nYou 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.\n\nBuild\n~~~~~\n\n.. code::\n\n cd doc\n make html\n\nYou can now find your generated documentation in `doc/_build/html/`.\n\nBy 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.\n\nConfiguration\n-------------\n\nThe following options are accepted:\n\n================= ====\nKey Type\n================= ====\n``doc_dir`` str\n``name`` str\n``parent_url`` str\n``logo_url`` str\n``favicon_url`` str\n``version`` str\n``release`` str\n``packages`` list\n``author`` str\n``copyright`` str\n``analytics`` str\n``canonical_url`` str\n================= ====\n\nThere 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.\n\ndoc_dir\n~~~~~~~\n\nThis is where your documentation lives.\n\n======= =======\nDefault Lookups\n======= =======\n``doc`` - ``source-dir`` in the ``build_sphinx`` section\n======= =======\n\nname\n~~~~\n\nThe name of your project.\n\n=========== =======\nDefault Lookups\n=========== =======\n``Project`` - ``project`` in the ``build_sphinx`` section\n - ``name`` in the ``metadata`` section\n - name of the current git repo\n=========== =======\n\nparent_url\n~~~~~~~~~~\n\nIf you are managing a `subproject <https://docs.readthedocs.io/en/stable/subprojects.html>`__, this is the URL of the main project. When set, DocInit adds a `Back` entry in the menu, and configures the `intersphinx mapping <https://www.sphinx-doc.org/en/master/usage/extensions/intersphinx.html>`__.\n\n======== =======\nDefault Lookups\n======== =======\n``None``\n======== =======\n\nlogo_url\n~~~~~~~~\n\nThe URL of an image that will be downloaded to `doc/_static/logo.png`. Useful for subprojects.\n\n======== =======\nDefault Lookups\n======== =======\n``None``\n======== =======\n\nfavicon_url\n~~~~~~~~~~~\n\nThe URL of an image that will be downloaded to `doc/_static/favicon.ico`. Useful for subprojects.\n\n======== =======\nDefault Lookups\n======== =======\n``None``\n======== =======\n\nversion\n~~~~~~~\n\nThe `semantic version <https://semver.org/>`__ of your package. If it is not explicitly defined, DocInit will use `setuptools_scm <https://github.com/pypa/setuptools_scm>`__ to fetch it from git tags, or fallback to ``0.0.0``.\n\n============== =======\nDefault Lookups\n============== =======\nFrom git tags - ``version`` in the ``build_sphinx`` section\n - ``version`` in the ``metadata`` section\n============== =======\n\nrelease\n~~~~~~~\n\nThe full version of your package, including VCS status. If it is not explicitly defined, DocInit will use `setuptools_scm <https://github.com/pypa/setuptools_scm>`__ to fetch it from git tags, or fallback to ``0.0.0``.\n\n============== =======\nDefault Lookups\n============== =======\nFrom git tags - ``release`` in the ``build_sphinx`` section\n============== =======\n\npackages\n~~~~~~~~\n\nThe 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).\n\n========= =======\nDefault Lookups\n========= =======\n``find:`` - ``packages`` in the ``options`` section\n========= =======\n\nauthor\n~~~~~~\n\nThe author of the project.\n\n============= =======\nDefault Lookups\n============= =======\n``Anonymous`` - ``author`` in the ``metadata`` section\n - From the first commit in the current git repository\n============= =======\n\ncopyright\n~~~~~~~~~\n\nThe 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``.\n\n========== =======\nDefault Lookups\n========== =======\nGenerated - ``copyright`` in the ``build_sphinx`` section\n========== =======\n\nanalytics\n~~~~~~~~~\n\nYour Google Analytics ID. It should look like ``UA-XXXXXXX-1``.\n\n======== =======\nDefault Lookups\n======== =======\n``None``\n======== =======\n\ncanonical_url\n~~~~~~~~~~~~~\n\nIf 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.\n\n======== =======\nDefault Lookups\n======== =======\n``None``\n======== =======\n\nArbitrary options\n~~~~~~~~~~~~~~~~~\n\nThat 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 <https://www.sphinx-doc.org/en/master/usage/configuration.html>`__ and `Sphinx AutoAPI <https://sphinx-autoapi.readthedocs.io/en/latest/reference/config.html>`__ documentation for recognized options.\n\nRead the docs\n-------------\n\nIf 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 <https://docs.readthedocs.io/en/stable/config-file/v2.html#packages>`__.\n\nThen you just need to invoke DocInit during the setup process.\n\nThis can be achieved in your `setup.py`:\n\n.. code:: python\n\n setup(\n ...\n setup_requires=\"docinit\",\n docinit=True,\n ...\n )\n\nOr if you prefer, in your `pyproject.toml`:\n\n.. code:: toml\n\n [tool.docinit]\n\n [build-system]\n requires = [\"setuptools>=42\", \"wheel\", \"docinit\"]\n build-backend = \"setuptools.build_meta\"\n\nPlease note: before version `20.1.b1` and since version `20.1.1`, `pip` `builds in a temporary directory <https://pip.pypa.io/en/stable/news/>`__. Therefore, on `Read The Docs` you need to install the package with `setup.py` so the documentation is generated in the current directory.\n\n\nAlternative build systems\n-------------------------\n\nDocInit currently only parses Setuptools `setup.cfg` files. We plan to add support for other build systems as well, such as `Flit <https://flit.readthedocs.io/>`__ and `Poetry <https://python-poetry.org/>`__, which rely on `pyproject.toml` files.\n\n\n.. |Build| image:: https://github.com/mesca/docinit/workflows/Python%20application/badge.svg\n.. |PyPI| image:: https://badge.fury.io/py/docinit.svg\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Bootstrap your Sphinx documentation",
"version": "0.18",
"split_keywords": [
"doc",
"autodoc",
"sphinx",
"apidoc"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "ed9377e060d4a3357dc0a11deafaeaa1879e3cc5bbcd94f3c714bb4fcf74bc97",
"md5": "33623d1101aae14dacaed2fec6eca4c5",
"sha256": "bb3bc28da03c792d39c88fa48c48bf58e177a619f1e0bb7b7afefef727135462"
},
"downloads": -1,
"filename": "docinit-0.18-py3-none-any.whl",
"has_sig": false,
"md5_digest": "33623d1101aae14dacaed2fec6eca4c5",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 14662,
"upload_time": "2023-04-25T17:30:40",
"upload_time_iso_8601": "2023-04-25T17:30:40.004746Z",
"url": "https://files.pythonhosted.org/packages/ed/93/77e060d4a3357dc0a11deafaeaa1879e3cc5bbcd94f3c714bb4fcf74bc97/docinit-0.18-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "d69098921b4042df758fe0129422c002748af69fe513c0b6a2d3ad324174f73e",
"md5": "ab5188cbce54dfd4802f13fa750617e7",
"sha256": "a402e664afc19a3b329c0789298a60ab5fba06511ae27a284d86d09985086d1f"
},
"downloads": -1,
"filename": "docinit-0.18.tar.gz",
"has_sig": false,
"md5_digest": "ab5188cbce54dfd4802f13fa750617e7",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 17431,
"upload_time": "2023-04-25T17:30:43",
"upload_time_iso_8601": "2023-04-25T17:30:43.087182Z",
"url": "https://files.pythonhosted.org/packages/d6/90/98921b4042df758fe0129422c002748af69fe513c0b6a2d3ad324174f73e/docinit-0.18.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-04-25 17:30:43",
"github": true,
"gitlab": false,
"bitbucket": false,
"github_user": "timeflux",
"github_project": "docinit",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "docinit"
}
JSON
