Documentation Builder for C++ and Python packages
=================================================
Breathing Cat is a tool for building documentation that is used for some of the
software packages developed at the Max Planck Institute for Intelligent Systems (MPI-IS)
and the New York University.
It is basically a wrapper around Doxygen, Sphinx and Breathe and runs those tools to
generate a Sphinx-based documentation, automatically including API documentation for
C++, Python and CMake code found in the package.
It is tailored to work with the structure of our packages but we are doing nothing
extraordinary there, so it will likely work for others as well (see below for the
assumptions we make regarding the package structure).
Installation
------------
Breathing Cat depends on [Doxygen](https://doxygen.nl) for generating C++ documentation.
As Doxygen cannot automatically be installed as dependency by pip, it needs to be
installed manually. For example on Ubuntu:
```
sudo apt install doxygen
```
To install Breathing Cat with all further dependencies:
```
pip install breathing_cat
```
Usage
-----
In the most simple case you can run it like this:
```
bcat --package-dir path/to/package --output-dir path/to/output
```
If no package version is specified, `bcat` tries to find it by checking a
number of files in the package directory. If no version is found this way, it fails
with an error. In this case, you can explicitly specify the version using
`--package-version`.
`bcat` tries to automatically detect if the package contains Python code and,
if yes, adds a Python API section to the documentation. However, if your package
contains Python modules that are only generated at build-time (e.g. Python bindings for
C++ code) you can use `--python-dir` to specify the directory where the Python modules
are installed to. This way, the generated modules will be included in the documentation
as well.
For a complete list of options see `bcat --help`.
Instead of the `bcat` executable, you can also use `python -m breathing_cat`.
Configuration
-------------
A package can contain an optional config file `breathing_cat.toml` which has to be
placed either in the root directory of the package or in `doc[s]/`.
Below is an exemplary config file, including all available options with their default
values:
```toml
[doxygen]
# List of patterns added to DOXYGEN_EXCLUDE_PATTERNS (see doxygen documentation).
# The string '{{PACKAGE_DIR}}' in the patterns is replaced with the path to the package.
# It is recommended to put this at the beginning of patterns to avoid unintended matches
# on higher up parts on the path, which would result in *all* the files of the package
# being excluded.
# Example:
# exclude_patterns = ["{{PACKAGE_DIR}}/include/some_third_party_lib/*"]
exclude_patterns = []
[intersphinx.mapping]
# Add intersphinx mappings. See intersphinx documentation for the meaning of the
# values.
# Two notations are supported:
#
# 1. Long notation (results in `'foo': ('docs.foo.org', 'my_inv.txt'):
# foo = {target = "docs.foo.org", inventory = "my_inv.txt"}
#
# 2. # Short notation (results in `'foo': ('docs.foo.org', None):
# foo = "docs.foo.org"
[html]
# Path to an image that is shown at the top of the navigation bar.
# The image should be located inside the "doc/" folder and the path given relative to
# the package root.
# Example:
# logo = "doc/images/logo.png"
logo = ""
[mainpage]
# Custom title for the main page. If not set "Welcome to {package}'s documentation!" is
# used.
# Example:
# title = "Custom Mainpage Title"
title = ""
# Automatically add files from the doc/ folder to a toctree, thus including them in the
# documentation. Set this to false if you want to manually provide a toctree in the
# doc_mainpage or README file.
auto_general_docs = true
```
Include Files From Source Directory in the Documentation
--------------------------------------------------------
You may want to include files from the package into the documentation text. For example
the package may contain a file `scripts/example.py` which could normally be included in
a file `doc/examples.rst` like this:
```rst
.. literalinclude:: ../scripts/example.py
```
With breathing cat, this unfortunately doesn't work, as all the documentation files are
copied to a separate build directory and processed there. From within this build
directory, the relative path given above cannot be resolved. However, a symlink called
"PKG" is created in the build directory and points to the package source directory. So
instead of the above, you can use the following (note the leading `/`):
```rst
.. literalinclude:: /PKG/scripts/example.py
```
Assumptions Regarding Package Structure
---------------------------------------
Breathing Cat makes the following assumptions regarding the structure of the documented
package:
- The directory containing the package has the same name as the actual package.
- If the package contains one of the following files (case insensitive) in the root
directory, it is included into the documentations main page:
```
doc_mainpage.rst, doc_mainpage.md, README.rst, README.md, README.txt, README
```
If there are multiple matches, only the first one is used with precedence based on the
list above.
Since `doc_mainpage.{rst,md}` has highest precedence, it can be provided in addition
to a README. This is useful if you want to have different content in the README and
on the documentation main page.
- The package may contain a license file called `LICENSE` or `license.txt`.
- C++ code is documented using Doxygen comments in the header files.
- C++ header files are located outside of `src/` (typically in `include/`).
- Python code is documented using docstrings (supported formats are standard Sphinx,
NumPy Style and Google Style).
- The Python code is located in one of the following directories (relative to the
package root):
- `<package_name>/`
- `python/<package_name>/`
- `src/<package_name>/`
- CMake files that should be documented are located in `cmake/` and use the directives
provided by the
[sphinxcontrib.moderncmakedomain](https://github.com/scikit-build/moderncmakedomain)
extension.
- General documentation is provided in reStructuredText- or Markdown-files located in
`doc/` or `docs/`. All files found in this directory are automatically included in
alphabetical order. This can be disabled via the config parameter
`mainpage.auto_general_docs` (see above) in case you want to manually provide a
toctree.
Copyright & License
-------------------
Copyright (c) 2022, New York University and Max Planck Gesellschaft.
License: BSD 3-clause (see LICENSE).
Raw data
{
"_id": null,
"home_page": "",
"name": "breathing-cat",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "Felix Widmaier <felix.widmaier@tuebingen.mpg.de>",
"keywords": "documentation,sphinx,doxygen",
"author": "Maximilien Naveau, Felix Widmaier",
"author_email": "",
"download_url": "https://files.pythonhosted.org/packages/6c/6b/1bd885ac19463ff4ce98b478054dd447773a1b6fb561e3bc4532044c2421/breathing_cat-1.3.0.tar.gz",
"platform": null,
"description": "Documentation Builder for C++ and Python packages\n=================================================\n\nBreathing Cat is a tool for building documentation that is used for some of the\nsoftware packages developed at the Max Planck Institute for Intelligent Systems (MPI-IS)\nand the New York University.\n\nIt is basically a wrapper around Doxygen, Sphinx and Breathe and runs those tools to\ngenerate a Sphinx-based documentation, automatically including API documentation for\nC++, Python and CMake code found in the package.\n\nIt is tailored to work with the structure of our packages but we are doing nothing\nextraordinary there, so it will likely work for others as well (see below for the\nassumptions we make regarding the package structure).\n\n\nInstallation\n------------\n\nBreathing Cat depends on [Doxygen](https://doxygen.nl) for generating C++ documentation.\nAs Doxygen cannot automatically be installed as dependency by pip, it needs to be\ninstalled manually. For example on Ubuntu:\n```\nsudo apt install doxygen\n```\n\nTo install Breathing Cat with all further dependencies:\n```\npip install breathing_cat\n```\n\n\nUsage\n-----\n\nIn the most simple case you can run it like this:\n\n```\nbcat --package-dir path/to/package --output-dir path/to/output\n```\n\nIf no package version is specified, `bcat` tries to find it by checking a\nnumber of files in the package directory. If no version is found this way, it fails\nwith an error. In this case, you can explicitly specify the version using\n`--package-version`.\n\n`bcat` tries to automatically detect if the package contains Python code and,\nif yes, adds a Python API section to the documentation. However, if your package\ncontains Python modules that are only generated at build-time (e.g. Python bindings for\nC++ code) you can use `--python-dir` to specify the directory where the Python modules\nare installed to. This way, the generated modules will be included in the documentation\nas well.\n\nFor a complete list of options see `bcat --help`.\n\nInstead of the `bcat` executable, you can also use `python -m breathing_cat`.\n\n\nConfiguration\n-------------\n\nA package can contain an optional config file `breathing_cat.toml` which has to be\nplaced either in the root directory of the package or in `doc[s]/`.\n\nBelow is an exemplary config file, including all available options with their default\nvalues:\n\n```toml\n[doxygen]\n# List of patterns added to DOXYGEN_EXCLUDE_PATTERNS (see doxygen documentation).\n# The string '{{PACKAGE_DIR}}' in the patterns is replaced with the path to the package.\n# It is recommended to put this at the beginning of patterns to avoid unintended matches\n# on higher up parts on the path, which would result in *all* the files of the package\n# being excluded.\n# Example:\n# exclude_patterns = [\"{{PACKAGE_DIR}}/include/some_third_party_lib/*\"]\nexclude_patterns = []\n\n\n[intersphinx.mapping]\n# Add intersphinx mappings. See intersphinx documentation for the meaning of the\n# values.\n# Two notations are supported:\n#\n# 1. Long notation (results in `'foo': ('docs.foo.org', 'my_inv.txt'):\n# foo = {target = \"docs.foo.org\", inventory = \"my_inv.txt\"}\n#\n# 2. # Short notation (results in `'foo': ('docs.foo.org', None):\n# foo = \"docs.foo.org\"\n\n\n[html]\n# Path to an image that is shown at the top of the navigation bar.\n# The image should be located inside the \"doc/\" folder and the path given relative to\n# the package root.\n# Example:\n# logo = \"doc/images/logo.png\"\nlogo = \"\"\n\n\n[mainpage]\n# Custom title for the main page. If not set \"Welcome to {package}'s documentation!\" is\n# used.\n# Example:\n# title = \"Custom Mainpage Title\"\ntitle = \"\"\n\n# Automatically add files from the doc/ folder to a toctree, thus including them in the\n# documentation. Set this to false if you want to manually provide a toctree in the\n# doc_mainpage or README file.\nauto_general_docs = true\n```\n\n\nInclude Files From Source Directory in the Documentation\n--------------------------------------------------------\n\nYou may want to include files from the package into the documentation text. For example\nthe package may contain a file `scripts/example.py` which could normally be included in\na file `doc/examples.rst` like this:\n\n```rst\n.. literalinclude:: ../scripts/example.py\n```\n\nWith breathing cat, this unfortunately doesn't work, as all the documentation files are\ncopied to a separate build directory and processed there. From within this build\ndirectory, the relative path given above cannot be resolved. However, a symlink called\n\"PKG\" is created in the build directory and points to the package source directory. So\ninstead of the above, you can use the following (note the leading `/`):\n\n```rst\n.. literalinclude:: /PKG/scripts/example.py\n```\n\n\nAssumptions Regarding Package Structure\n---------------------------------------\n\nBreathing Cat makes the following assumptions regarding the structure of the documented\npackage:\n\n- The directory containing the package has the same name as the actual package.\n- If the package contains one of the following files (case insensitive) in the root\n directory, it is included into the documentations main page:\n ```\n doc_mainpage.rst, doc_mainpage.md, README.rst, README.md, README.txt, README\n ```\n If there are multiple matches, only the first one is used with precedence based on the\n list above.\n\n Since `doc_mainpage.{rst,md}` has highest precedence, it can be provided in addition\n to a README. This is useful if you want to have different content in the README and\n on the documentation main page.\n- The package may contain a license file called `LICENSE` or `license.txt`.\n- C++ code is documented using Doxygen comments in the header files.\n- C++ header files are located outside of `src/` (typically in `include/`).\n- Python code is documented using docstrings (supported formats are standard Sphinx,\n NumPy Style and Google Style).\n- The Python code is located in one of the following directories (relative to the\n package root):\n\n - `<package_name>/`\n - `python/<package_name>/`\n - `src/<package_name>/`\n\n- CMake files that should be documented are located in `cmake/` and use the directives\n provided by the\n [sphinxcontrib.moderncmakedomain](https://github.com/scikit-build/moderncmakedomain)\n extension.\n- General documentation is provided in reStructuredText- or Markdown-files located in\n `doc/` or `docs/`. All files found in this directory are automatically included in\n alphabetical order. This can be disabled via the config parameter\n `mainpage.auto_general_docs` (see above) in case you want to manually provide a\n toctree.\n\n\nCopyright & License\n-------------------\n\nCopyright (c) 2022, New York University and Max Planck Gesellschaft.\n\nLicense: BSD 3-clause (see LICENSE).\n",
"bugtrack_url": null,
"license": "",
"summary": "Tool to build documentation for C++/Python-Packages used at MPI-IS",
"version": "1.3.0",
"split_keywords": [
"documentation",
"sphinx",
"doxygen"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "38eecedbeacdbd905b3efc6f97c04fed3bb63f72f02aeb327e66023158049ad5",
"md5": "53e21fbfe405e50aef90eb492d3fc6ec",
"sha256": "73ea619bdd0266f748121c809d5162a2d2b9b9cfb4ff8bcfdaedb0b157bfab92"
},
"downloads": -1,
"filename": "breathing_cat-1.3.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "53e21fbfe405e50aef90eb492d3fc6ec",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 20520,
"upload_time": "2023-03-14T10:46:25",
"upload_time_iso_8601": "2023-03-14T10:46:25.892512Z",
"url": "https://files.pythonhosted.org/packages/38/ee/cedbeacdbd905b3efc6f97c04fed3bb63f72f02aeb327e66023158049ad5/breathing_cat-1.3.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "6c6b1bd885ac19463ff4ce98b478054dd447773a1b6fb561e3bc4532044c2421",
"md5": "4d0d83687c7bb2f908567eb4cfb998d2",
"sha256": "59ca8a4f00a3884443a6627bc3f300bd65b788e5d07fd57225561d0ab13f3f18"
},
"downloads": -1,
"filename": "breathing_cat-1.3.0.tar.gz",
"has_sig": false,
"md5_digest": "4d0d83687c7bb2f908567eb4cfb998d2",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 22819,
"upload_time": "2023-03-14T10:46:27",
"upload_time_iso_8601": "2023-03-14T10:46:27.933239Z",
"url": "https://files.pythonhosted.org/packages/6c/6b/1bd885ac19463ff4ce98b478054dd447773a1b6fb561e3bc4532044c2421/breathing_cat-1.3.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-03-14 10:46:27",
"github": false,
"gitlab": false,
"bitbucket": false,
"lcname": "breathing-cat"
}
JSON