#ansible-docs: Documentation Working Group aka DaWGs

Meeting started by samccann at 14:31:28 UTC (full logs).

Meeting summary

  1. opening chatter (acozine, 14:34:56)
    1. agenda https://github.com/ansible/community/issues/521#issuecomment-721211831 (samccann, 14:38:35)

  2. version split and supplementary meeting (acozine, 14:40:05)
    1. Thurs supplemental meeting minutes from last week - https://github.com/ansible/community/issues/521#issuecomment-721211489 (samccann, 14:44:05)
    2. weekly Thurs supplemental meeting starts 10:30am ET on #ansible-docs to cover splitting the docsite (samccann, 14:44:51)
    3. folks are getting confused between ansible-base and Ansible (the names are too similar) -someone somewhere might want to consider renaming one of them (samccann, 14:46:14)

  3. removing docs files from Ansible tarballs (acozine, 14:49:15)
    1. need to be careful on naming the docs package so no one confuses it with `ansible-doc` the cli command (samccann, 14:59:09)
    2. https://en.wikipedia.org/wiki/AsciiDoc (felixfontein, 15:02:28)
    3. rst were included in main tarball, we used to have downstream packagers generate htmls and the afformentioned 'ansible-docs' packages (samccann, 15:12:08)
    4. AGREED: we'll build an `ansible-documentation` package so the documentation is available to those who want it but the main `ansible` package stays slim; when the time comes we'll build an `ansible-core-documentation` package also (acozine, 15:16:21)
    5. first step would be to build the documentation package, get it published with new releases, and only then kick out docs from the existing package (felixfontein, 15:19:48)

  4. sphinx extension (felixfontein, 15:21:47)
    1. there's a PR in the antsibull repository for the sphinx plugin: https://github.com/ansible-community/antsibull/pull/210 (felixfontein, 15:22:01)

  5. extending collection docs (felixfontein, 15:22:34)
  6. extending collection docs (https://github.com/ansible/community/issues/521#issuecomment-723579328) (felixfontein, 15:22:41)
    1. https://github.com/ansible-collections/ansible.utils/tree/main/docs (acozine, 15:28:03)
    2. ACTION: samccann to followup on docs problems with ansible.utils - hey use something that is similar to module/plugin docs, but not officially defined by ansible-base, like https://github.com/ansible-collections/ansible.utils/blob/main/plugins/test/validate.py (samccann, 15:28:25)
    3. existing filter/test plugins can contain multiple different plugins in one file .. so the ansible.utils approach won't help (samccann, 15:29:44)
    4. ACTION: bcoca to post link to his WIP PR for docs in any plugin type (filters/tests etc) (samccann, 15:36:32)
    5. roles argspec is wip. see https://github.com/ansible/ansible/pull/72120 ... might be more prs (samccann, 15:38:38)
    6. https://www.youtube.com/ansible-community (gundalow, 15:39:08)
    7. https://github.com/sensu/sensu-go-ansible/blob/master/roles/install/README.md for example. (tadeboro, 15:43:13)
    8. - there are competing needs/wants from a collection /docs folder. (samccann, 15:50:38)
    9. it would probably help to involve all that are currently working on docs of some kind - galaxy, ansible.util, roles argspec, bcoca's branch, antsibull-docs (samccann, 15:52:08)
    10. who/what will consume the files within a collection /docs folder? AH/galaxy-ng? docs.ansible.com in the future? ...gasp...access.redhat.com? (samccann, 15:55:00)
    11. - what's the timeline for getting fitler/test plugins documentable and working with `ansible-doc` and how does this relate to wha `ansible.utils` is doing in their Dec release? (samccann, 15:58:18)
    12. what is the timeline for the roles argspec and does it solve all the roles documentation needs, or will roles also want manually written docs within a collection /docs folder (and thus need subfolders which aren't supported today? (samccann, 16:01:22)
    13. can we also support other manual docs, like scenario guides in the collection /docs folder etc? (samccann, 16:02:19)


Meeting ended at 16:04:31 UTC (full logs).

Action items

  1. samccann to followup on docs problems with ansible.utils - hey use something that is similar to module/plugin docs, but not officially defined by ansible-base, like https://github.com/ansible-collections/ansible.utils/blob/main/plugins/test/validate.py
  2. bcoca to post link to his WIP PR for docs in any plugin type (filters/tests etc)


Action items, by person

  1. bcoca
    1. bcoca to post link to his WIP PR for docs in any plugin type (filters/tests etc)
  2. samccann
    1. samccann to followup on docs problems with ansible.utils - hey use something that is similar to module/plugin docs, but not officially defined by ansible-base, like https://github.com/ansible-collections/ansible.utils/blob/main/plugins/test/validate.py


People present (lines said)

  1. samccann (115)
  2. acozine (114)
  3. felixfontein (103)
  4. bcoca (52)
  5. tadeboro (27)
  6. zodbot (11)
  7. gundalow (9)
  8. tremble (4)
  9. lmodemal (2)
  10. dmsimard (1)
  11. dericcrago (1)


Generated by MeetBot 0.1.4.