{"id":15140721,"url":"https://github.com/ansible/ansible-documentation","last_synced_at":"2025-10-05T16:43:34.931Z","repository":{"id":173782369,"uuid":"651282842","full_name":"ansible/ansible-documentation","owner":"ansible","description":"Ansible community documentation","archived":false,"fork":false,"pushed_at":"2025-04-06T00:13:35.000Z","size":210201,"stargazers_count":105,"open_issues_count":113,"forks_count":599,"subscribers_count":17,"default_branch":"devel","last_synced_at":"2025-04-06T08:05:09.309Z","etag":null,"topics":["ansible","documentation","hacktoberfest"],"latest_commit_sha":null,"homepage":"https://docs.ansible.com/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ansible.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"COPYING","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-06-08T23:05:38.000Z","updated_at":"2025-04-04T05:23:01.000Z","dependencies_parsed_at":"2024-04-15T13:05:12.147Z","dependency_job_id":"7cba334f-0fec-40b8-87c4-bca200597609","html_url":"https://github.com/ansible/ansible-documentation","commit_stats":{"total_commits":49168,"total_committers":6351,"mean_commits":7.741772949141867,"dds":0.9295069964204361,"last_synced_commit":"fd41e247016bb38cb970ee2c6120a8f08ec2813b"},"previous_names":["ansible/ansible-docsite","ansible/ansible-documentation"],"tags_count":108,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ansible%2Fansible-documentation","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ansible%2Fansible-documentation/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ansible%2Fansible-documentation/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ansible%2Fansible-documentation/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ansible","download_url":"https://codeload.github.com/ansible/ansible-documentation/tar.gz/refs/heads/devel","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248709172,"owners_count":21149140,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ansible","documentation","hacktoberfest"],"created_at":"2024-09-26T08:40:24.299Z","updated_at":"2025-10-05T16:43:29.909Z","avatar_url":"https://github.com/ansible.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ansible-documentation\n\nThis repository holds the ReStructuredText (RST) source, and other files, for user documentation related to the Ansible package and Ansible Core.\n\n\u003e Documentation for modules and plugins that are officially supported by the Ansible Core engineering team is available in the [`ansible/ansible`](https://github.com/ansible/ansible) repository.\n\n## Verifying your pull request\n\nWe welcome all contributions to Ansible community documentation.\nIf you plan to submit a pull request with changes, you should [verify your PR](https://docs.ansible.com/ansible/latest/community/documentation_contributions.html#verifying-your-documentation-pr) to ensure it conforms with style guidelines and can build successfully.\n\n### Setting up nox\n\nThis project includes a `nox` configuration to automate tests, checks, and other functions.\nYou can use these automated tests to help you verify changes before you submit a PR.\nYou can manually\n[set up your environment](https://docs.ansible.com/ansible/latest/community/documentation_contributions.html#setting-up-your-environment-to-build-documentation-locally)\nif you prefer, but `nox` is more straightforward and create an isolated environment for you.\n\n* Install `nox` using `python3 -m pip install nox` or your distribution's package manager.\n\n* Execute `nox` from the repository root with no arguments to run\n  all docs checkers, Python code checkers, and a minimal HTML docs build.\n\n* Alternatively, you can run only certain tasks as outlined in the following sections.\n  Run `nox --list` to view available sessions.\n\n### Building docs\n\nThe different Makefile targets used to build the documentation are outlined in\n[Building the documentation locally](https://docs.ansible.com/ansible/latest/community/documentation_contributions.html#building-the-documentation-locally).\nThe `nox` configuration has a `make` session that creates a build environment and uses the Makefile to generate HTML.\n\n* Clone required parts of the `ansible/ansible` repository.\n\n  ``` bash\n  nox -s clone-core\n  ```\n\n  See [Periodically cloning Ansible core](https://docs.ansible.com/ansible/latest/community/documentation_contributions.html#periodically-cloning-ansible-core) for more information.\n\n* Build minimal Ansible Core docs.\n\n  ``` bash\n  nox -s make\n  ```\n\n* Run a specific Makefile target:\n\n  ``` bash\n  nox -s make -- clean htmlsingle rst=community/documentation_contributions.rst\n  ```\n\n### Running automated tests\n\nThe `nox` configuration also contains session to run automated docs checkers.\n\n* Ensure there are no syntax errors in the reStructuredText source files.\n\n  ``` bash\n  nox -s \"checkers(rstcheck)\"\n  ```\n\n  See [Running the final tests](https://docs.ansible.com/ansible/latest/community/documentation_contributions.html#running-the-final-tests) for more information.\n\n* Verify the docs build.\n\n  ``` bash\n  nox -s \"checkers(docs-build)\"\n  ```\n\n  This session cleans the generated docs after it runs.\n  If you want to view the generated HTML in your browser, you should build the documentation locally.\n  See [Building the documentation locally](https://docs.ansible.com/ansible/latest/community/documentation_contributions.html#building-the-documentation-locally) for more information.\n\n* Lint, type check, and format Python scripts in this repository.\n\n  ``` bash\n  nox -s lint\n  ```\n\n  The `actionlint` linter that is run as part of the `lint` session requires\n  `podman` or `docker` to be installed.\n  If both container engines are installed, `podman` is preferred.\n  Set `CONTAINER_ENGINE=docker` to change this behavior.\n\n### Checking spelling\n\nUse [`codespell`](https://github.com/codespell-project/codespell) to check for common spelling mistakes in the documentation source.\n\n* Check spelling.\n\n  ``` bash\n  nox -s spelling\n  ```\n\n* Correct any detected spelling errors.\n\n  ``` bash\n  nox -s spelling -- -w\n  ```\n\n* Select an option when `codespell` suggests more than one word as a correction.\n\n  ``` bash\n  nox -s spelling -- -w -i 3\n  ```\n\n## Dependency files\n\n`nox` sessions use dependencies from requirements files in the `tests/` directory.\nEach session has a `tests/{name}.in` file with direct dependencies and a lock file in `tests/{name}.txt` that pins *exact versions* for both direct and transitive dependencies.\nThe lock files contain tested dependencies that are automatically updated on a weekly basis.\n\nIf you'd like to use untested dependencies, set `PINNED=false` as in the following example:\n\n```bash\nPINNED=false nox -s \"checkers(docs-build)\"\n```\n\nFor more details about using unpinned and tested dependencies for doc builds, see [Setting up your environment to build documentation locally](https://docs.ansible.com/ansible/latest/community/documentation_contributions.html#setting-up-your-environment-to-build-documentation-locally).\n\n## Updating dependencies\n\nUse the following `nox` session to update the dependency lock files in `tests/`.\n\n  ``` bash\n  nox -s pip-compile\n  ```\n\nTo synchronize dependency lock files with base requirements files without changing transitive dependencies, use the `--no-upgrade` flag:\n\n  ``` bash\n  nox -s pip-compile -- --no-upgrade\n  ```\n\nTo upgrade a single dependency, for instance when adjusting constraints on a package, use the `--upgrade-package` flag followed by the package name:\n\n  ``` bash\n  nox -s pip-compile -- --upgrade-package \u003cpackage_name\u003e\n  ```\n\n## Creating release tags\n\nWhen a tag is created in the [`ansible/ansible`](https://github.com/ansible/ansible) repository for a release or release candidate, a corresponding tag should be created in this `ansible-documentation` repository.\n\nFirst, ensure that you have the [`ansible/ansible`](https://github.com/ansible/ansible) and [`ansible/ansible-documentation`](https://github.com/ansible/ansible-documentation) repositories checked out.\nThe tool assumes that both checkouts have the same parent directory. You can set different paths to your checkouts with the `--docs` and `--core` options if you have them set up another way.\n\nNext, run the `tag` `nox` session.\n\nThis will determine any missing `ansible-core` tags and create them in `ansible-documentation` if needed, exiting normally otherwise:\n\n``` bash\n# The tagger scripts assumes \"origin\" as the upstream remote.\nnox -s tag\n\n# If you use a different upstream remote, specify the name.\nnox -s tag -- --remote \u003cname\u003e tag\n\n# If your core repo is not in the same filesystem location, specify the path.\nnox -s tag -- --core \u003cpath\u003e tag\n```\n\nSee `nox -s tag -- --help` for extended options.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fansible%2Fansible-documentation","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fansible%2Fansible-documentation","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fansible%2Fansible-documentation/lists"}