Don’t paste files into the docs. Include the files instead.

[ypid]

Currently, the docs/getting-started.rst contain something like this:

Example playbook
----------------

Here's an example playbook that can be used to manage cryptsetup::

    ---
    - name: Configure encrypted filesystems
      hosts: [ 'debops_service_cryptsetup' ]
      become: True

      roles:

        - role: debops.cryptsetup
          tags: [ 'role::cryptsetup' ]

Why not just place the playbook as is into docs/playbooks/${role_name}.yml and then include it into the rendered docs like so:

.. literalinclude:: playbooks/cryptsetup.yml
   :language: yaml

Advantages

• The playbook can be directly used by users instead of copying it from the docs (e. g. introducing redundancy)
• No indention moving stuff.
• This allows to more easily sync the playbooks and the documentation. So we could treat the playbook in the role as source and then update the playbooks in the playbooks repos automatically.

Example role: https://github.com/ypid/ansible-x2go_server/tree/master/docs

[drybjed]

I agree that this would make roles easier to use, especially for those that don't use the full DebOps project. Putting the playbooks in docs/playbooks/ seems a little counter-productive though. Perhaps putting them in the main role directory, in plays/ or playbooks/ (not sure which spelling would be better, since there's already vars/ and defaults/ meaning short name and full name) would make them more accessible. Using a separate directory would allow for a set of multiple different playbooks (for example one with just a role, and another with dependent roles included), but that shouldn't be a requiremment. I'm also not sure about the filename convention - named after a role vs static name, which could allow automation (although that could be handled via symlinks).

[drybjed]

Coincidentally,I thought about using playbooks included with the roles in similar fashion in the main debops-playbooks repository somehow, but I don't see a reliable way, short of writing an extensive script that could search different role directories and pick out playbooks, so I dropped that. However, if it's useful in some way to others, I'm not against it. :-)

[ypid]

Thanks for your input. I decided to go with putting the playbook(s) under docs for two reasons:

1. Ansible might restrict what files/directories are allowed to be present in the role in future releases.
2. I think it kind of fits into the documentation of the role as it is just an example.

But I am also ok with putting it into playbooks/. For the name, I guess some static name is probably better especially when there are more then one playbook. I guess something like common.yml cloud be used for the playbook included in debops-playbooks.

[drybjed]

If these playbooks are meant to be just examples then sure, I suppose putting them in docs/playbooks/ should be safer. Let's go with that.

I would be wary of reusing common.yml for role playbook name, it might get confusing, since common.yml playbook is one of the important and most used ones. Perhaps going with docs/playbooks/<role-name>.yml for the default example playbook will be enough? This reflects the usage in debops-playbooks repository, with role playbooks stored as service/<role-name>.yml.

[ypid]

Sounds good. Ok so for the default playbook we can use the role name. And for additional playbooks?

I have one practical example for this:

• https://github.com/debops/debops-playbooks/blob/master/playbooks/service/apt_cacher_ng.yml → docs/playbooks/apt_cacher_ng.yml
• https://github.com/debops-contrib/debops-contrib-playbooks/blob/master/service/apt_cacher_ng.yml → docs/playbooks/apt_cacher_ng-apparmor.yml ? or apt_cacher_ng+apparmor.yml ?

[drybjed]

I would go with -, + is seems much more rare and prone to being important in filenames. Although I don't think setting some restrictions for other playbooks than the default one would be needed, unless that's impotant for Sphinx for URL resolution when multiple roles could use similar names like:

.. literalinclude:: playbooks/example.yml
   :language: yaml

I imagine that could result in a collision... So yeah, let's go with playbook names prefixed with role name.

[ypid]

OK. Decision summary:

• docs/playbooks/apt_cacher_ng.yml for the playbook used in DebOps.
  Example: https://github.com/debops/debops-playbooks/blob/master/playbooks/service/apt_cacher_ng.yml
• docs/playbooks/apt_cacher_ng-apparmor.yml example for a playbook based on the one in DebOps which additionally uses debops-contrib.apparmor.
  Example: https://github.com/debops-contrib/debops-contrib-playbooks/blob/master/service/apt_cacher_ng.yml