| Name | antsibull-docs JSON |
| Version |
2.16.3
JSON |
| download |
| home_page | None |
| Summary | Tools for building Ansible documentation |
| upload_time | 2025-01-16 19:40:42 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.9 |
| license | None |
| keywords |
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
<!--
Copyright (c) Ansible Project
GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
SPDX-License-Identifier: GPL-3.0-or-later
-->
# antsibull-docs -- Ansible Documentation Build Scripts
[](https://matrix.to/#/#antsibull:ansible.com)
[](https://matrix.to/#/#docs:ansible.com)
[](https://github.com/ansible-community/antsibull-docs/actions/workflows/nox.yml)
[](https://github.com/ansible-community/antsibull-docs/actions?query=workflow%3A%22antsibull-docs+tests%22+branch%3Amain)
[](https://github.com/ansible-community/antsibull-docs/actions?query=workflow%3A%22Build+CSS%22+branch%3Amain)
[](https://codecov.io/gh/ansible-community/antsibull-docs)
[](https://api.reuse.software/info/github.com/ansible-community/antsibull-docs)
Tooling for building Ansible documentation. This is mainly the `antsibull-docs` command and the [Sphinx extension](https://www.sphinx-doc.org/en/master/), ``sphinx_antsibull_ext``. Please check out the [documentation](https://ansible.readthedocs.io/projects/antsibull-docs/) for more information.
You can find a list of changes in [the antsibull-docs changelog](https://github.com/ansible-community/antsibull-docs/blob/main/CHANGELOG.md).
antsibull-docs is covered by the [Ansible Code of Conduct](https://docs.ansible.com/ansible/latest/community/code_of_conduct.html).
## Community
Need help or want to discuss the project? See our [Community guide](https://ansible.readthedocs.io/projects/antsibull-docs/community/) to learn how to join the conversation!
## Versioning and compatibility
From version 1.0.0 on, antsibull-docs sticks to semantic versioning and aims at providing no backwards compatibility breaking changes **to the command line API (antsibull-docs)** during a major release cycle. We might make exceptions from this in case of security fixes for vulnerabilities that are severe enough.
The current major version is 2.x.y. Development for 2.x.y occurs on the `main` branch. 2.x.y mainly differs from 1.x.y by dropping support for Python 3.6, 3.7, and 3.8, and by dropping support for older Ansible/ansible-base/ansible-core versions. See the changelog for details. 1.x.y is still developed on the `stable-1` branch, but only security fixes, major bugfixes, and other absolutely necessary changes will be backported.
We explicitly exclude code compatibility. **antsibull-docs is not supposed to be used as a library.** The only exception are potential dependencies with other antsibull projects (currently there are none). If you want to use a certain part of antsibull-docs as a library, please create an issue so we can discuss whether we add a stable interface for **parts** of the Python code. We do not promise that this will actually happen though.
If you are interested in library support for interpreting Ansible markup, please take a look at [the antsibull-docs-parser project](https://github.com/ansible-community/antsibull-docs-parser).
## Development
Install and run `nox` to run all tests. That's it for simple contributions!
`nox` will create virtual environments in `.nox` inside the checked out project
and install the requirements needed to run the tests there.
---
antsibull-docs depends on the sister antsibull-changelog, antsibull-core,
antsibull-docs-parser, antsibull-docutils, and antsibull-fileutils projects.
By default, `nox` will install a development version of these projects from Github.
If you're hacking on antsibull-changelog, antsibull-core, antsibull-docs-parser,
antsibull-docutils, and/or antsibull-fileutils alongside antsibull-docs,
nox will automatically install the projects from `../antsibull-changelog`,
`../antsibull-core`, `../antsibull-docs-parser`, `../antsibull-docutils`,
and `../antsibull-fileutils` when running tests if those paths exist.
You can change this behavior through the `OTHER_ANTSIBULL_MODE` env var:
- `OTHER_ANTSIBULL_MODE=auto` — the default behavior described above
- `OTHER_ANTSIBULL_MODE=local` — install the projects from `../antsibull-changelog`,
`../antsibull-core`, `../antsibull-docs-parser`, `../antsibull-docutils`, and
`../antsibull-fileutils`.
Fail if those paths don't exist.
- `OTHER_ANTSIBULL_MODE=git` — install the projects from the Github main branch
- `OTHER_ANTSIBULL_MODE=pypi` — install the latest versions from PyPI
---
To run specific tests:
1. `nox -e test` to only run unit tests;
2. `nox -e lint` to run all linters and formatter;
3. `nox -e codeqa` to run `flake8`, `pylint`, `reuse lint`, and `antsibull-changelog lint`;
4. `nox -e formatters` to run `isort` and `black`;
5. `nox -e typing` to run `mypy`.
To create a more complete local development env:
```console
git clone https://github.com/ansible-community/antsibull-changelog.git
git clone https://github.com/ansible-community/antsibull-core.git
git clone https://github.com/ansible-community/antsibull-docs-parser.git
git clone https://github.com/ansible-community/antsibull-docs.git
git clone https://github.com/ansible-community/antsibull-docutils.git
cd antsibull-docs
python3 -m venv venv
. ./venv/bin/activate
pip install -e '.[dev]' -e ../antsibull-changelog -e ../antsibull-core -e ../antsibull-docs-parser -e ../antsibull-docutils
[...]
nox
```
## Updating the CSS file for the Sphinx extension
The CSS file [sphinx_antsibull_ext/antsibull-minimal.css](https://github.com/ansible-community/antsibull-docs/blob/main/sphinx_antsibull_ext/antsibull-minimal.css) is built from [sphinx_antsibull_ext/css/antsibull-minimal.scss](https://github.com/ansible-community/antsibull-docs/blob/main/sphinx_antsibull_ext/src/antsibull-minimal.scss) using [SASS](https://sass-lang.com/) and [postcss](https://postcss.org/) using [autoprefixer](https://github.com/postcss/autoprefixer) and [cssnano](https://cssnano.co/).
Use the script `build.sh` in `sphinx_antsibull_ext/css/` to build the `.css` file from the `.scss` file:
```console
cd sphinx_antsibull_ext/css/
./build-css.sh
```
For this to work, you need to install some Node.js dependencies:
```console
npm clean-install
```
## Creating a new release:
1. Run `nox -e bump -- <version> <release_summary_message>`. This:
* Bumps the package version in `src/antsibull_docs/__init__.py`.
* Creates `changelogs/fragments/<version>.yml` with a `release_summary` section.
* Runs `antsibull-changelog release --version <version>` and adds the changed files to git.
* Commits with message `Release <version>.` and runs `git tag -a -m 'antsibull-docs <version>' <version>`.
* Runs `hatch build --clean`.
2. Run `git push` to the appropriate remotes.
3. Once CI passes on GitHub, run `nox -e publish`. This:
* Runs `hatch publish`;
* Bumps the version to `<version>.post0`;
* Adds the changed file to git and run `git commit -m 'Post-release version bump.'`;
4. Run `git push --follow-tags` to the appropriate remotes and create a GitHub release.
## License
Unless otherwise noted in the code, it is licensed under the terms of the GNU
General Public License v3 or, at your option, later. See
[LICENSES/GPL-3.0-or-later.txt](https://github.com/ansible-community/antsibull-docs/tree/main/LICENSE)
for a copy of the license.
The repository follows the [REUSE Specification](https://reuse.software/spec/) for declaring copyright and
licensing information. The only exception are changelog fragments in ``changelog/fragments/``.
Raw data
{
"_id": null,
"home_page": null,
"name": "antsibull-docs",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": "Felix Fontein <felix@fontein.de>, Maxwell G <maxwell@gtmx.me>",
"keywords": null,
"author": null,
"author_email": "Toshio Kuratomi <a.badger@gmail.com>, Felix Fontein <felix@fontein.de>",
"download_url": "https://files.pythonhosted.org/packages/9c/bb/066215c559e5e73561010cee16e74f8d54aeb1afd318a1a5ed928562438f/antsibull_docs-2.16.3.tar.gz",
"platform": null,
"description": "<!--\nCopyright (c) Ansible Project\nGNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)\nSPDX-License-Identifier: GPL-3.0-or-later\n-->\n\n# antsibull-docs -- Ansible Documentation Build Scripts\n[](https://matrix.to/#/#antsibull:ansible.com)\n[](https://matrix.to/#/#docs:ansible.com)\n[](https://github.com/ansible-community/antsibull-docs/actions/workflows/nox.yml)\n[](https://github.com/ansible-community/antsibull-docs/actions?query=workflow%3A%22antsibull-docs+tests%22+branch%3Amain)\n[](https://github.com/ansible-community/antsibull-docs/actions?query=workflow%3A%22Build+CSS%22+branch%3Amain)\n[](https://codecov.io/gh/ansible-community/antsibull-docs)\n[](https://api.reuse.software/info/github.com/ansible-community/antsibull-docs)\n\nTooling for building Ansible documentation. This is mainly the `antsibull-docs` command and the [Sphinx extension](https://www.sphinx-doc.org/en/master/), ``sphinx_antsibull_ext``. Please check out the [documentation](https://ansible.readthedocs.io/projects/antsibull-docs/) for more information.\n\nYou can find a list of changes in [the antsibull-docs changelog](https://github.com/ansible-community/antsibull-docs/blob/main/CHANGELOG.md).\n\nantsibull-docs is covered by the [Ansible Code of Conduct](https://docs.ansible.com/ansible/latest/community/code_of_conduct.html).\n\n## Community\n\nNeed help or want to discuss the project? See our [Community guide](https://ansible.readthedocs.io/projects/antsibull-docs/community/) to learn how to join the conversation!\n\n## Versioning and compatibility\n\nFrom version 1.0.0 on, antsibull-docs sticks to semantic versioning and aims at providing no backwards compatibility breaking changes **to the command line API (antsibull-docs)** during a major release cycle. We might make exceptions from this in case of security fixes for vulnerabilities that are severe enough.\n\nThe current major version is 2.x.y. Development for 2.x.y occurs on the `main` branch. 2.x.y mainly differs from 1.x.y by dropping support for Python 3.6, 3.7, and 3.8, and by dropping support for older Ansible/ansible-base/ansible-core versions. See the changelog for details. 1.x.y is still developed on the `stable-1` branch, but only security fixes, major bugfixes, and other absolutely necessary changes will be backported.\n\nWe explicitly exclude code compatibility. **antsibull-docs is not supposed to be used as a library.** The only exception are potential dependencies with other antsibull projects (currently there are none). If you want to use a certain part of antsibull-docs as a library, please create an issue so we can discuss whether we add a stable interface for **parts** of the Python code. We do not promise that this will actually happen though.\n\nIf you are interested in library support for interpreting Ansible markup, please take a look at [the antsibull-docs-parser project](https://github.com/ansible-community/antsibull-docs-parser).\n\n## Development\n\nInstall and run `nox` to run all tests. That's it for simple contributions!\n`nox` will create virtual environments in `.nox` inside the checked out project\nand install the requirements needed to run the tests there.\n\n---\n\nantsibull-docs depends on the sister antsibull-changelog, antsibull-core,\nantsibull-docs-parser, antsibull-docutils, and antsibull-fileutils projects.\nBy default, `nox` will install a development version of these projects from Github.\nIf you're hacking on antsibull-changelog, antsibull-core, antsibull-docs-parser,\nantsibull-docutils, and/or antsibull-fileutils alongside antsibull-docs,\nnox will automatically install the projects from `../antsibull-changelog`,\n`../antsibull-core`, `../antsibull-docs-parser`, `../antsibull-docutils`,\nand `../antsibull-fileutils` when running tests if those paths exist.\nYou can change this behavior through the `OTHER_ANTSIBULL_MODE` env var:\n\n- `OTHER_ANTSIBULL_MODE=auto` \u2014 the default behavior described above\n- `OTHER_ANTSIBULL_MODE=local` \u2014 install the projects from `../antsibull-changelog`,\n `../antsibull-core`, `../antsibull-docs-parser`, `../antsibull-docutils`, and\n `../antsibull-fileutils`.\n Fail if those paths don't exist.\n- `OTHER_ANTSIBULL_MODE=git` \u2014 install the projects from the Github main branch\n- `OTHER_ANTSIBULL_MODE=pypi` \u2014 install the latest versions from PyPI\n\n---\n\nTo run specific tests:\n\n1. `nox -e test` to only run unit tests;\n2. `nox -e lint` to run all linters and formatter;\n3. `nox -e codeqa` to run `flake8`, `pylint`, `reuse lint`, and `antsibull-changelog lint`;\n4. `nox -e formatters` to run `isort` and `black`;\n5. `nox -e typing` to run `mypy`.\n\nTo create a more complete local development env:\n\n```console\ngit clone https://github.com/ansible-community/antsibull-changelog.git\ngit clone https://github.com/ansible-community/antsibull-core.git\ngit clone https://github.com/ansible-community/antsibull-docs-parser.git\ngit clone https://github.com/ansible-community/antsibull-docs.git\ngit clone https://github.com/ansible-community/antsibull-docutils.git\ncd antsibull-docs\npython3 -m venv venv\n. ./venv/bin/activate\npip install -e '.[dev]' -e ../antsibull-changelog -e ../antsibull-core -e ../antsibull-docs-parser -e ../antsibull-docutils\n[...]\nnox\n```\n\n## Updating the CSS file for the Sphinx extension\n\nThe CSS file [sphinx_antsibull_ext/antsibull-minimal.css](https://github.com/ansible-community/antsibull-docs/blob/main/sphinx_antsibull_ext/antsibull-minimal.css) is built from [sphinx_antsibull_ext/css/antsibull-minimal.scss](https://github.com/ansible-community/antsibull-docs/blob/main/sphinx_antsibull_ext/src/antsibull-minimal.scss) using [SASS](https://sass-lang.com/) and [postcss](https://postcss.org/) using [autoprefixer](https://github.com/postcss/autoprefixer) and [cssnano](https://cssnano.co/).\n\nUse the script `build.sh` in `sphinx_antsibull_ext/css/` to build the `.css` file from the `.scss` file:\n\n```console\ncd sphinx_antsibull_ext/css/\n./build-css.sh\n```\n\nFor this to work, you need to install some Node.js dependencies:\n\n```console\nnpm clean-install\n```\n\n## Creating a new release:\n\n1. Run `nox -e bump -- <version> <release_summary_message>`. This:\n * Bumps the package version in `src/antsibull_docs/__init__.py`.\n * Creates `changelogs/fragments/<version>.yml` with a `release_summary` section.\n * Runs `antsibull-changelog release --version <version>` and adds the changed files to git.\n * Commits with message `Release <version>.` and runs `git tag -a -m 'antsibull-docs <version>' <version>`.\n * Runs `hatch build --clean`.\n2. Run `git push` to the appropriate remotes.\n3. Once CI passes on GitHub, run `nox -e publish`. This:\n * Runs `hatch publish`;\n * Bumps the version to `<version>.post0`;\n * Adds the changed file to git and run `git commit -m 'Post-release version bump.'`;\n4. Run `git push --follow-tags` to the appropriate remotes and create a GitHub release.\n\n## License\n\nUnless otherwise noted in the code, it is licensed under the terms of the GNU\nGeneral Public License v3 or, at your option, later. See\n[LICENSES/GPL-3.0-or-later.txt](https://github.com/ansible-community/antsibull-docs/tree/main/LICENSE)\nfor a copy of the license.\n\nThe repository follows the [REUSE Specification](https://reuse.software/spec/) for declaring copyright and\nlicensing information. The only exception are changelog fragments in ``changelog/fragments/``.\n",
"bugtrack_url": null,
"license": null,
"summary": "Tools for building Ansible documentation",
"version": "2.16.3",
"project_urls": {
"Bug tracker": "https://github.com/ansible-community/antsibull-docs/issues",
"Changelog": "https://github.com/ansible-community/antsibull-docs/tree/main/CHANGELOG.md",
"Code of Conduct": "https://docs.ansible.com/ansible/latest/community/code_of_conduct.html",
"Documentation": "https://ansible.readthedocs.io/projects/antsibull-docs/",
"Source code": "https://github.com/ansible-community/antsibull-docs"
},
"split_keywords": [],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "7456c6beaf622eb32162de5a739d6d0dcde9ccba4c48eee2e4d916f95a0f30d5",
"md5": "88348a4873ab573b2bd3d282e6420612",
"sha256": "d27fcb90d5ab37aca3afc68305a27b79fcc6203a11ea46051cde620d52d6cb10"
},
"downloads": -1,
"filename": "antsibull_docs-2.16.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "88348a4873ab573b2bd3d282e6420612",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 277346,
"upload_time": "2025-01-16T19:40:38",
"upload_time_iso_8601": "2025-01-16T19:40:38.010525Z",
"url": "https://files.pythonhosted.org/packages/74/56/c6beaf622eb32162de5a739d6d0dcde9ccba4c48eee2e4d916f95a0f30d5/antsibull_docs-2.16.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "9cbb066215c559e5e73561010cee16e74f8d54aeb1afd318a1a5ed928562438f",
"md5": "a015f1339a5e559c4824b7be812c43f1",
"sha256": "e62106eb7e4e85646693992d55297d47d63aff5ca599a0eccfdcca1d896898a2"
},
"downloads": -1,
"filename": "antsibull_docs-2.16.3.tar.gz",
"has_sig": false,
"md5_digest": "a015f1339a5e559c4824b7be812c43f1",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 1462327,
"upload_time": "2025-01-16T19:40:42",
"upload_time_iso_8601": "2025-01-16T19:40:42.569284Z",
"url": "https://files.pythonhosted.org/packages/9c/bb/066215c559e5e73561010cee16e74f8d54aeb1afd318a1a5ed928562438f/antsibull_docs-2.16.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-01-16 19:40:42",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "ansible-community",
"github_project": "antsibull-docs",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "antsibull-docs"
}
