community.general/docs/docsite/helper/keep_keys

Docs helper. Create RST file.

The playbook playbook.yml writes a RST file that can be used in docs/docsite/rst. The usage of this helper is recommended but not mandatory. You can stop reading here and update the RST file manually if you don't want to use this helper.

Run the playbook

If you want to generate the RST file by this helper fit the variables in the playbook and the template to your needs. Then, run the play

shell> ansible-playbook playbook.yml

Copy RST to docs/docsite/rst

Copy the RST file to docs/docsite/rst and remove it from this directory.

Update the checksums

Substitute the variables and run the below commands

shell> sha1sum {{ target_vars }} > {{ target_sha1 }}
shell> sha1sum {{ file_rst }} > {{ file_sha1 }}

Playbook explained

The playbook includes the variable tests from the integration tests and creates the RST file from the template. The playbook will terminate if:

• The file with the variable tests was changed
• The RST file was changed

This means that this helper is probably not up to date.

The file with the variable tests was changed

This means that somebody updated the integration tests. Review the changes and update the template if needed. Update the checksum to pass the integrity test. The playbook message provides you with the command.

The RST file was changed

This means that somebody updated the RST file manually. Review the changes and update the template. Update the checksum to pass the integrity test. The playbook message provides you with the command. Make sure that the updated template will create identical RST file. Only then apply your changes.