# MkDocs Ansible Collection
[MkDocs](https://www.mkdocs.org) Plugin that automatically generates documentation pages for Ansible Collections. Check out the showcase over on the project's [documentation page](https://mkdocs-ansible-collection.readthedocs.io/en/latest/showcase/)!
## Quick Start
1. Add the `mkdocs-ansible-collection` package to your project's docs dependencies. It will also install `ansible-core` to manage collections and get the required metadata.
```
pip install mkdocs-ansible-collection
```
2. Install any needed collection(s) using `ansible-galaxy collection install <names>` or point ansible at the correct collection path.
3. Enable the plugin in your project's `mkdocs.yml` file:
```yaml
plugins:
- "ansible-collection":
collections:
- fqcn: "collection.example"
```
4. Add an anchor page to the `nav` section of your project's `mkdocs.yml` file:
```yaml
nav:
# The anchor is named after the Collection FQCN and it tells mkdocs where
# to generate the documentation tree. The following examples show all of
# the currently supported combinations:
- "Ansible Builtins": "ansible.builtin"
- "Collection Showcase":
- "showcase/index.md"
- "ansible.posix"
- "networktocode.nautobot"
```
For more details, check out the detailed [User Guide](user_guide.md) and look at the documentation example of [this project's docs](https://github.com/cmsirbu/mkdocs-ansible-collection) themselves which showcase how to build and host collection docs on the awesome [Read the Docs](https://about.readthedocs.com/) service!
### Requirements and Compatibility
To generate the pages dynamically at build time, the plugin uses metadata exported by the `ansible-doc` tool, which must be installed together with the collections you want to generate documentation for in your environment.
The plugin has been built for `mkdocs >= 1.6.0` and has only been tested with the [Material for MkDocs](https://squidfunk.github.io/mkdocs-material/) theme.
## Developing
To set up the development environment, run the following commands in the project root:
```
poetry install
poetry run mkdocs serve
```
## Contributions
!!! warning Work in Progress
This plugin is under initial development - you can track progress towards the first fully functional release [here](https://github.com/cmsirbu/mkdocs-ansible-collection/milestone/1).
Contributions of all sorts (bug reports, features, documentation etc.) are welcome! If you're not sure about any of the changes you are proposing, please open a new issue to discuss it first.
Raw data
{
"_id": null,
"home_page": "https://github.com/cmsirbu/mkdocs-ansible-collection",
"name": "mkdocs-ansible-collection",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=3.9",
"maintainer_email": null,
"keywords": null,
"author": "Cristian Sirbu",
"author_email": "cristian@trueneutral.eu",
"download_url": "https://files.pythonhosted.org/packages/10/51/3503b367844bcda5369db929c7b3c86bfbeea52c23b0bc8ee72f82559314/mkdocs_ansible_collection-0.2.1.tar.gz",
"platform": null,
"description": "# MkDocs Ansible Collection\n\n[MkDocs](https://www.mkdocs.org) Plugin that automatically generates documentation pages for Ansible Collections. Check out the showcase over on the project's [documentation page](https://mkdocs-ansible-collection.readthedocs.io/en/latest/showcase/)!\n\n## Quick Start\n\n1. Add the `mkdocs-ansible-collection` package to your project's docs dependencies. It will also install `ansible-core` to manage collections and get the required metadata.\n\n ```\n pip install mkdocs-ansible-collection\n ```\n\n2. Install any needed collection(s) using `ansible-galaxy collection install <names>` or point ansible at the correct collection path.\n\n3. Enable the plugin in your project's `mkdocs.yml` file:\n\n ```yaml\n plugins:\n - \"ansible-collection\":\n collections:\n - fqcn: \"collection.example\"\n ```\n\n4. Add an anchor page to the `nav` section of your project's `mkdocs.yml` file:\n\n ```yaml\n nav:\n # The anchor is named after the Collection FQCN and it tells mkdocs where\n # to generate the documentation tree. The following examples show all of\n # the currently supported combinations:\n - \"Ansible Builtins\": \"ansible.builtin\"\n - \"Collection Showcase\":\n - \"showcase/index.md\"\n - \"ansible.posix\"\n - \"networktocode.nautobot\"\n ```\n\nFor more details, check out the detailed [User Guide](user_guide.md) and look at the documentation example of [this project's docs](https://github.com/cmsirbu/mkdocs-ansible-collection) themselves which showcase how to build and host collection docs on the awesome [Read the Docs](https://about.readthedocs.com/) service!\n\n### Requirements and Compatibility\n\nTo generate the pages dynamically at build time, the plugin uses metadata exported by the `ansible-doc` tool, which must be installed together with the collections you want to generate documentation for in your environment.\n\nThe plugin has been built for `mkdocs >= 1.6.0` and has only been tested with the [Material for MkDocs](https://squidfunk.github.io/mkdocs-material/) theme.\n\n## Developing\n\nTo set up the development environment, run the following commands in the project root:\n\n```\npoetry install\npoetry run mkdocs serve\n```\n\n## Contributions\n\n!!! warning Work in Progress\n\n This plugin is under initial development - you can track progress towards the first fully functional release [here](https://github.com/cmsirbu/mkdocs-ansible-collection/milestone/1).\n\nContributions of all sorts (bug reports, features, documentation etc.) are welcome! If you're not sure about any of the changes you are proposing, please open a new issue to discuss it first.\n\n",
"bugtrack_url": null,
"license": null,
"summary": "MkDocs Plugin that automatically generates pages for Ansible Collections.",
"version": "0.2.1",
"project_urls": {
"Homepage": "https://github.com/cmsirbu/mkdocs-ansible-collection",
"Repository": "https://github.com/cmsirbu/mkdocs-ansible-collection"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "22fcd414df1c142e4668230d6862bcaa2cd0c45daca6781aa2d600497dc089b1",
"md5": "7f4151968e1945b0f6686493e9f519c5",
"sha256": "efb4957d9af90c416d89de1f00fafbc922535c84682f8d6c8446eabd30cb00be"
},
"downloads": -1,
"filename": "mkdocs_ansible_collection-0.2.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "7f4151968e1945b0f6686493e9f519c5",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.9",
"size": 10061,
"upload_time": "2024-11-16T14:11:33",
"upload_time_iso_8601": "2024-11-16T14:11:33.809309Z",
"url": "https://files.pythonhosted.org/packages/22/fc/d414df1c142e4668230d6862bcaa2cd0c45daca6781aa2d600497dc089b1/mkdocs_ansible_collection-0.2.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "10513503b367844bcda5369db929c7b3c86bfbeea52c23b0bc8ee72f82559314",
"md5": "e68be835a692732b7ddbf75f7275a600",
"sha256": "02526b2b4062569757b96cabee81febe3904beb032518fcd5c6122f4c6a84758"
},
"downloads": -1,
"filename": "mkdocs_ansible_collection-0.2.1.tar.gz",
"has_sig": false,
"md5_digest": "e68be835a692732b7ddbf75f7275a600",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.9",
"size": 8410,
"upload_time": "2024-11-16T14:11:35",
"upload_time_iso_8601": "2024-11-16T14:11:35.637516Z",
"url": "https://files.pythonhosted.org/packages/10/51/3503b367844bcda5369db929c7b3c86bfbeea52c23b0bc8ee72f82559314/mkdocs_ansible_collection-0.2.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-11-16 14:11:35",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "cmsirbu",
"github_project": "mkdocs-ansible-collection",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "mkdocs-ansible-collection"
}
JSON
