search

ansible-collections / community.hashi_vault

Ansible collection for managing and working with HashiCorp Vault.
https://docs.ansible.com/ansible/devel/collections/community/hashi_vault/index.html
GNU General Public License v3.0
80 stars 59 forks source link

docs - lookup guide #211

Closed briantist closed 2 years ago

briantist commented 2 years ago
SUMMARY

Adds a lookup guide to the docsite. This discusses topics such as:

~This PR also includes the changes in https://github.com/ansible-community/antsibull/pull/391 since we commit the output of antsibull sphinx-init in the collection (so developers can build local docs more easily and so we can slightly customize the index page).~ ^ these changes were moved to #215 .

ISSUE TYPE
COMPONENT NAME

docsite

ADDITIONAL INFORMATION

N/A

github-actions[bot] commented 2 years ago

Docs Build 📝

Thank you for contribution!✨

The docs for this PR have been published here: https://community-hashi-vault-pr211.surge.sh

You can compare to the docs for the main branch here:

The docsite for this PR is also available for download as an artifact from this run: https://github.com/ansible-collections/community.hashi_vault/actions/runs/1775686828

File changes:

Click to see the diff comparison. **NOTE:** only file modifications are shown here. New and deleted files are excluded. See the file list and check the published docs to see those files. ```diff diff --git a/home/runner/work/community.hashi_vault/community.hashi_vault/docsbuild/base/collections/community/hashi_vault/docsite/contributor_guide.html b/home/runner/work/community.hashi_vault/community.hashi_vault/docsbuild/head/collections/community/hashi_vault/docsite/contributor_guide.html index 88b026a..21cb7e9 100644 --- a/home/runner/work/community.hashi_vault/community.hashi_vault/docsbuild/base/collections/community/hashi_vault/docsite/contributor_guide.html +++ b/home/runner/work/community.hashi_vault/community.hashi_vault/docsbuild/head/collections/community/hashi_vault/docsite/contributor_guide.html @@ -21,7 +21,7 @@ - + @@ -167,9 +167,9 @@

  1. Log into your GitHub account.

  2. Fork the ansible-collections/community.hashi_vault repository by clicking the Fork button in the upper right corner. This will create a fork in your own account.

    3. -

  3. Clone the repository locally, following the example instructions here (but replace general with hashi_vault). Pay special attention to the local path structure of the cloned repository as described in those instructions (for example ansible_collections/community/hashi_vault).

    4. +

  4. Clone the repository locally, following the example instructions here (but replace general with hashi_vault). Pay special attention to the local path structure of the cloned repository as described in those instructions (for example ansible_collections/community/hashi_vault).

  5. As mentioned on that page, commit your changes to a branch, push them to your fork, and create a pull request (GitHub will automatically prompt you to do so when you look at your repository).

    6. -

  6. See the guidance on Changelogs and include a changelog fragment if appropriate.

    7. +

  7. See the guidance on Changelogs and include a changelog fragment if appropriate.

@@ -184,15 +184,15 @@

Module and plugin documentation

-

This type of documentation gets generated from structured YAML, inside of a Python string. It is included in the same code that it’s documenting, or in a separate Python file, such as a doc fragment. Please see the module format and documentation guidance for more information.

-

This type of documentation is highly structured and tested with ansible-test sanity. Full instructions are available on the testing module documentation page.

+

This type of documentation gets generated from structured YAML, inside of a Python string. It is included in the same code that it’s documenting, or in a separate Python file, such as a doc fragment. Please see the module format and documentation guidance for more information.

+

This type of documentation is highly structured and tested with ansible-test sanity. Full instructions are available on the testing module documentation page.

Additionally, the docsite build on pull requests (or built locally) will include module and plugin documentation as well. See the next section for details.

Collection docsite

-

The collection docsite is what you are reading now. It is written in reStructuredText (RST) format and published on the ansible_documentation site. This is where we have long-form documentation that doesn’t fit into the other two categories.

+

The collection docsite is what you are reading now. It is written in reStructuredText (RST) format and published on the ansible_documentation site. This is where we have long-form documentation that doesn’t fit into the other two categories.

If you are considering adding an entirely new document here it may be best to open a GitHub issue first to discuss the idea and how best to organize it.

-

Refer to the Ansible style guide for all submissions to the collection docsite.

+

Refer to the Ansible style guide for all submissions to the collection docsite.

RST files for the docsite are in the docs/docsite/rst/ directory. Some submissions may also require edits to docs/docsite/extra-docs.yml.

When a pull request is submitted which changes the collection’s documentation, a new docsite will be generated and published to a temporary site, and a bot will post a comment on the PR with a link. This will let you see the rendered docs to help with spotting formatting errors.

It’s also possible to build the docs locally, by installing some extra Python requirements and running the build script:

@@ -207,7 +207,7 @@

Running tests locally

If you’re making anything more than very small or one-time changes, run the tests locally to avoid having to push a commit for each thing, and waiting for the CI to run tests.

-

First, review the guidance on testing collections, as it applies to this collection as well.

+

First, review the guidance on testing collections, as it applies to this collection as well.

Integration Tests

Unlike other collections, we require an integration_config.yml file for properly running integration tests, as the tests require external dependencies (like a Vault server) and they need to know where to find those dependencies.

@@ -386,7 +386,7 @@