#ansible-docs: Docs Working Group aka DaWGs

Meeting started by acozine at 15:01:25 UTC (full logs).

Meeting summary

  1. opening chatter (acozine, 15:01:31)
  2. suggestions from the docs user survey (acozine, 15:08:23)
    1. docs survey feedback issues opened - https://github.com/ansible/ansible/issues?q=Docs+survey+feedback (samccann, 15:11:11)
    2. feedback and help both welcome particularly on https://github.com/ansible/ansible/issues/75507 (acozine, 15:12:41)
    3. https://gist.github.com/pierrejoubert73/902cc94d79424356a8d20be2b382e1ab (briantist, 15:19:08)
    4. maybe there is a way to add expand/collapse to sphinx output so users can more easily expand the examples section - https://guido.vonrudorff.de/2013/sphinx-documentation-collapse-content/ (samccann, 15:21:01)
    5. an example of a good 'pattern' book for examples is https://docs.ansible.com/ansible/latest/user_guide/complex_data_manipulation.html (samccann, 15:23:10)
    6. That particular sphinx expance uses jquery and might not be good on screen readers (samccann, 15:23:42)
    7. an example pattern book should also include output (samccann, 15:24:01)
    8. for expand collapse - see https://github.com/readthedocs/sphinx_rtd_theme/issues/402 for some hints (samccann, 15:25:09)
    9. https://stackoverflow.com/questions/2454577/sphinx-restructuredtext-show-hide-code-snippets/60394068#60394068 might be useful, though it's ugly (on sphinx side) (felixfontein, 15:26:34)
    10. another useful expand/collapse thread - https://stackoverflow.com/questions/2454577/sphinx-restructuredtext-show-hide-code-snippets/60394068#60394068 (samccann, 15:27:37)
    11. some sphinx extension which generates <details></details> (with <summary><summary/>) would probably be best (samccann, 15:28:49)
    12. ACTION: samccann to open an issue on the ansible theme to ask for expand/collapse capability (samccann, 15:29:25)
    13. this would be good on something like the pattern example pages. we could either expand/collapse each code snippet example, or we could divide each example into three parts (data, expression, output) and collapse/expand them separately (samccann, 15:32:30)
    14. and possibly expand to module docs in the future (samccann, 15:32:49)
    15. ACTION: samccann create a topic issue for the community WG on community-contributed examples (samccann, 15:41:38)

  3. sphinx redirects (acozine, 15:42:36)
    1. https://github.com/ansible/ansible/pull/75502/files is a WIP PR that uses Sphinx for redirects instead of apache config (acozine, 15:43:01)
    2. this PR proves it works for simple 1-1 redirects and would make the redirects visible to the community (samccann, 15:44:56)
    3. redirects extension is https://pypi.org/project/sphinx-reredirects/ (samccann, 15:46:42)
    4. https://gitlab.com/documatt/sphinx-reredirects (samccann, 15:47:14)
    5. https://tech.signavio.com/2017/managing-sphinx-redirects (samccann, 15:52:14)

  4. open floor (acozine, 15:52:41)
    1. install instructions for debian are woefully outdated (trusty is old, calver is newer) - https://docs.ansible.com/ansible/latest/installation_guide/intro_installation.html#installing-ansible-on-debian (samccann, 15:57:50)
    2. on ubuntu vs debian releases https://libera.ems.host/_matrix/media/r0/download/libera.chat/7e35f2f92ea3844b184705c5f1f2f053df59ffc7/message.txt (samccann, 16:01:47)
    3. ACTION: dericcrago to open a PR to update the debian install instrtuctions (samccann, 16:04:04)
    4. briantist looking for collection maintainers to collaborate on docs build enhancements (acozine, 16:07:14)
    5. some details on testing collection docs before merging - https://github.com/ansible-collections/community.hashi_vault/blob/main/.github/workflows/docs.yml (samccann, 16:11:56)


Meeting ended at 16:15:25 UTC (full logs).

Action items

  1. samccann to open an issue on the ansible theme to ask for expand/collapse capability
  2. samccann create a topic issue for the community WG on community-contributed examples
  3. dericcrago to open a PR to update the debian install instrtuctions


Action items, by person

  1. dericcrago
    1. dericcrago to open a PR to update the debian install instrtuctions
  2. samccann
    1. samccann to open an issue on the ansible theme to ask for expand/collapse capability
    2. samccann create a topic issue for the community WG on community-contributed examples


People present (lines said)

  1. acozine (118)
  2. samccann (88)
  3. briantist (25)
  4. dericcrago (14)
  5. zodbot (10)
  6. felixfontein (6)
  7. gwmngilfen-work (3)
  8. gundalow (1)


Generated by MeetBot 0.1.4.