DaWGs (Documentation Working Group) Meeting Agenda 2021

[acozine]

Closing this issue. Please add agenda items to the new 2022 issue - https://github.com/ansible/community/issues/643

This tracks the DaWGs (Documentation Working Group )meetings for Ansible docs, starting from Jan. 2021.

This team uses the following GitHub tracking boards:

• ansible Base (covering all the user/developer guides etc)
• Ansible-maintained collections - what needs to happen in docs for these collections.
• docs pipeline - the work and dependencies to getting module docs from collections back onto docs.ansible.com/ansible.

If you have a question, comment, idea, or anything else to discuss, please leave a comment here to add it to the agenda for our next meeting. If you don't show up for the meeting, your item will probably be skipped.

If your IRC nick is different from your Github username, leave that as well.

See https://github.com/ansible/community/blob/master/meetings/README.md for the schedule.

Once an item has been addressed please edit the text to make it strike-through style (two tildes ~~ on either side of the text) or check the checkbox if available.

When creating new agenda ensure docs and meeting_agenda labels are set.

Join us anytime in #ansible-docs on libera IRC!

See #521 for 2020 minutes and #389 for prior meeting minutes.

[acozine]

2021-01-05

long-running issues from

• https://www.irccloud.com/pastebin/hNYJt512/list%20of%20long-running%20topics
• :+1: remove bitflip release process from the active agenda for now
• https://meetbot.fedoraproject.org/ansible-docs/2020-12-15/dawgs_aka_docs_working_group.2020-12-15-16.01.log.html if you want to see it
• last we talked about module formatting, we decided to check how many C(), I() etc is already in the docs. Then create a proposal for full semantic markup based on how hard it would be to change everything
• ansible-docs code removes markup so not a big impact if we go to semantic or other markup changes
• CI may not be possible to enforce markup down the road, but might be if we choose good markup names?
• https://docs.ansible.com/ansible/latest/dev_guide/developing_modules_documenting.html#linking-and-other-format-macros-within-module-documentation

do we or don't we adopt semantic markup

• :+1: - create a WIP PR that changes the documentation to what we are proposing (semantic) and use that for review/feedback
• https://www.irccloud.com/pastebin/zyXyNCqJ/

open floor

• if you have question, concern, or idea related to Ansible docs, you can bring it up in the ansible-docs channel at any time, or add it to the DaWGs meeting agenda by adding a comment to https://github.com/ansible/community/issues/579
• everyone is welcome in the channel and in all meetings
• we will have the supplemental docs meeting on Thurs at 10:30ET to discuss/update on the docsite split

Actions

• [x] @acozine to create a WIP PR that illustrates proposed semantic markup, solicit feedback

Logs

Minutes: https://meetbot.fedoraproject.org/ansible-docs/2021-01-05/docs_working_group_aka_dawgs.2021-01-05-16.00.html Minutes (text): https://meetbot.fedoraproject.org/ansible-docs/2021-01-05/docs_working_group_aka_dawgs.2021-01-05-16.00.txt Log: https://meetbot.fedoraproject.org/ansible-docs/2021-01-05/docs_working_group_aka_dawgs.2021-01-05-16.00.log.html

[acozine]

Contributing to Ansible Documentation

Easy Places you can help!

• Updating docs to use FQCN in collections - https://github.com/ansible-collections/overview/issues/89
• edits to https://github.com/ansible/ansibullbot/blob/master/docs/collection_migration.md
• all Docs issues
• Docs PRs needing reviews/merges

Less easy but need developer help on:

• improve `ansible-test documentation - https://github.com/ansible/ansible/issues/70555

interesting links

• ansible Base (covering all the user/developer guides etc)
• Ansible-maintained collections - what needs to happen in docs for these collections.
• docs pipeline - the work and dependencies to getting module docs from collections back onto docs.ansible.com/ansible.

[acozine]

2021-01-07

status update

• problem statement - the ansible PyPI package called version 3.0.0 will beta at start of Feb 2021 timeframe and some time after that, the ansible-core PyPI package called version 2.11 will release. We need a way for docs to reflect the two “streams” of versions. Ansible 3.0.0 docs need to reference back to ansible-base 2.10 docs for all Ansible features that are not collections.
• proposal docs.ansible.com/ansible becomes Ansible the Package documentation. docs.ansible.com/ansible-core becomes the core only documentation.
• current status Reviewing internally to get full buyin from management later this week
• Today's meeting goals - implementation - assuming we get approval, how can we accomplish all this in 3 weeks and 2 days (to have a docsite for 3.0.0 beta)
• agenda - https://github.com/ansible/community/issues/579#issuecomment-750471248

what must we accomplish by Feb 2 and what can we push off to a later

• proposal https://hackmd.io/TQmzyhCUSSKa22iFR_079A?both
• :+1: we need a docsite that reflects Ansible 3.0.0, that doesn't mess up older releases, and that has /devel/ for ansible-core
• :+1: we will not try to unversion any existing docs (aka community/developer guide) by Feb 2.
• https://docs.ansible.com/ansible/devel/roadmap/COLLECTIONS_3_0.html that seems to refer to 2.11
• If a user installs Ansible 3.x it will never install ansible=core 2.11
• Ansible 4.x would never install core-2.12 either
• Docs will reflect what is in Ansible the package and not attempt to match what a user may manually upgrade after that

new repo for new community guides etc

• We know there are various gaps in the community documentation, especially around how to look after (maintain, own, manage) Collection & Collection repos. We have a lot of brand new docs to write. Currently we've been using https://github.com/ansible-collections/overview to host some RST. Though this was always viewed as a short term solution
• I wonder if we could start a new top level docsite for these brand new docs (docs.ansible.com/community)
• Example index page https://hackmd.io/uKhHRhFUStG_bVNhY10cLQ#New-Index-structure

Actions

• [x] @samccann abadger1999 to continue discussing how to build this 3.x docsite from some 2.10 rst files later today

Logs

Minutes: https://meetbot.fedoraproject.org/ansible-docs/2021-01-07/documentation_working_group_supplemental_meeting.2021-01-07-15.31.html Minutes (text): https://meetbot.fedoraproject.org/ansible-docs/2021-01-07/documentation_working_group_supplemental_meeting.2021-01-07-15.31.txt Log: https://meetbot.fedoraproject.org/ansible-docs/2021-01-07/documentation_working_group_supplemental_meeting.2021-01-07-15.31.log.html

notes on brainstorming session

https://hackmd.io/x0VwaKSYQCaHGJR4LelSEw?view

dev guide - people will need 2.10 info, some devel info, some will need both. this is a case that either a unified dev guide that includes the differences between older versions and newer versions or an index page with the different versions of various documents would attempt to solve.

• contributor to ansible-core: needs devel info.
• collection creator: probably needs both.
• private module person: needs latest stable release Our best option is to attempt to create the unversioned dev guide out of /devel/ and go back in to mark what is new for 2.11 (or 3.x) based on commit/prs.

[samccann]

2021-01-12

role argspec update

• decided to place the argspec in meta/main.yml under the argument_specs entry. that was to satisfy a request from felixfontein for future docs reasons.
• we have no doc specific requirements spec'd for it at this time, but i would expect that to be filled out after the initial PoC phase.
• 2.11 you can expect: 1) validates role args at task execution time from spec in meta/main.yml, 2) ansible-doc support to output role entrypoints and descriptions.
• the role arg spec format will be a subset of module arg spec. they will, in fact, share the same code.
• removing the "update on role argspec" from the agenda for the next few months, will add it back as a regular item after 2.11 release

template for collection /docs/ folder

• directory: we're going to propose allocating a specific subdirectory in the collection for building docsite content from. Nothing unrelated to the docsite should be placed there.
• need 'some way' to make labels unique across all the collections
• an example of a potential label would be .. _anscoll_community_crypto_LABEL:: (_anscoll_communitycrypto is the part that uniquifies the label.
• need a way to exclude collections whose docs are bad (for instance, contain conflicting labels) or include the collections that are known good.
• https://github.com/sensu/sensu-go-ansible/blob/master/docs/Makefile.custom is what we do to render things.

docs user survey results

• 27% said they were "very happy" and another 33% said they were "slightly happy" with the Ansible docs
• only 9.6% said they were "very unhappy"
• https://stats.eng.ansible.com/apps/docs/docs-survey.html
• raw data from the survey (more insights to come later ) - https://stats.eng.ansible.com/apps/docs/docs-survey.html

open floor

• https://github.com/ansible-community/antsibull/pull/231#issuecomment-757371797

Actions

• [x] @tadeboro to investigate ways to move forward with role docs as we wait for role argspec validation
• [x] @acozine to summarize today's conversation in a proposal or issue

Logs

Minutes: https://meetbot.fedoraproject.org/ansible-docs/2021-01-12/docs_working_group_aka_dawgs.2021-01-12-16.01.html Minutes (text): https://meetbot.fedoraproject.org/ansible-docs/2021-01-12/docs_working_group_aka_dawgs.2021-01-12-16.01.txt Log: https://meetbot.fedoraproject.org/ansible-docs/2021-01-12/docs_working_group_aka_dawgs.2021-01-12-16.01.log.html

[samccann]

2021-01-14

Status of the docsite split proposal

• the proposal is at https://hackmd.io/TQmzyhCUSSKa22iFR_079A?both
• we have internal buyin to make this happen!
• we have a plan for how to achieve this - https://hackmd.io/x0VwaKSYQCaHGJR4LelSEw?view
• TL;DR; - two sites with nearly identical documentation for now since we are short on time. They will have separate urls and versions.
• tracking issue for all we have to accomplish this month - https://github.com/ansible/ansible/issues/72032

problems to solve

• http://docs.testing.ansible.com/ansible-core/2.11/
• https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#substitution-definitions
• https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#substitution-references
• https://sublime-and-sphinx-guide.readthedocs.io/en/latest/reuse.html
• rst substitutions might work - https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#substitution-definitions and https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#substitution-references
• see https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#substitutions for how to do this w separate files

list of problems to solve

• this is an older list of problems abadger1999 created a few weeks ago - https://hackmd.io/iDEyihLqRtWnjtOUd3pNYQ
• this problem still exists - https://hackmd.io/iDEyihLqRtWnjtOUd3pNYQ#Pipeline-uses-Ansible-version-to-set-the-version-in-the-URL-for-docs

Next Steps

• :+1: we will stop having this extra meeting and fold updates/issues into the regular tuesday DaWGs meetings
• acozine working on jenkins build samccann working on makefile lmodemal working on variable subsitution
• abadger1999 investigating the antsibull side of this to see if it 'all works' or needs some changes
• more information also available on the project board at https://github.com/ansible/ansible/projects/27

Actions

• [x] @lmodemal - attempt sphinx/rst variable substitution for the title
• [x] @samccann to clarify what this problem really means - https://hackmd.io/iDEyihLqRtWnjtOUd3pNYQ#Pipeline-uses-Ansible-version-to-set-the-version-in-the-URL-for-docs

Logs

Minutes: https://meetbot.fedoraproject.org/ansible-docs/2021-01-14/dawgs_aka_documentation_working_group_supplemental_meeting.2021-01-14-15.32.html Minutes (text): https://meetbot.fedoraproject.org/ansible-docs/2021-01-14/dawgs_aka_documentation_working_group_supplemental_meeting.2021-01-14-15.32.txt Log: https://meetbot.fedoraproject.org/ansible-docs/2021-01-14/dawgs_aka_documentation_working_group_supplemental_meeting.2021-01-14-15.32.log.html

[felixfontein]

• [x] Porting guide for Ansible 3.0.0 (since Ansible 3 uses the same ansible-base major release as Ansible 2.10): https://github.com/ansible-community/antsibull/pull/231#issuecomment-757371797

[samccann]

2021-01-19

opening chatter

• https://docs.ansible.com/ansible/ < missing index

open floor

• no more Thursday supplemental DaWGs meeting. We are implementing the docsite split now and will cover details in Tuesday meetings
• docsite work is progressing. We will post here when we have test site updates available for review.

Actions

• [x] @dmsimard to backport PR that adds FQCN to glossary

Logs

Minutes: https://meetbot.fedoraproject.org/ansible-docs/2021-01-19/docs_working_group_aka_dawgs.2021-01-19-16.00.html Minutes (text): https://meetbot.fedoraproject.org/ansible-docs/2021-01-19/docs_working_group_aka_dawgs.2021-01-19-16.00.txt Log: https://meetbot.fedoraproject.org/ansible-docs/2021-01-19/docs_working_group_aka_dawgs.2021-01-19-16.00.log.html

adding breadcrumbs to the plugin pages

• https://github.com/ansible-community/antsibull/pull/240
• acozine ended the main meeting too early, mea culpa
• the PR would add index pages at the namespace level
• example of the breadcrumbs in action: https://ansible.fontein.de/collections/community/crypto/x509_certificate_module.html

Logs

Minutes: https://meetbot.fedoraproject.org/ansible-docs/2021-01-19/docs_working_group_meeting_extension.2021-01-19-16.55.html Minutes (text): https://meetbot.fedoraproject.org/ansible-docs/2021-01-19/docs_working_group_meeting_extension.2021-01-19-16.55.txt Log: https://meetbot.fedoraproject.org/ansible-docs/2021-01-19/docs_working_group_meeting_extension.2021-01-19-16.55.log.html

[felixfontein]

• [x] ansible-community/antsibull#240 breadcrumbs for module/plugin/collection docs; and collection namespace indexes

[samccann]

2021-01-26

Docsite Split Update

• WIP PR for docsite split is https://github.com/ansible/ansible/pull/73362 - still a lot to go on it
• we also have an internal build that can publish 'make coredocs' once we have all this working
• this line controls what collection version gets included in the docs build -https://github.com/ansible/ansible/blob/devel/hacking/build_library/build_ansible/command_plugins/docs_build.py#L17
• (1) git clone ansible (2) source hacking/en-setup (3) run build-ansible.py which uses docs_build to build the docs (4) docs_build imports ansible.release.version from the ansible checkout and gets the version (5) docs_build executes antsibull-docs with that version
• https://github.com/ansible/ansible/blob/devel/hacking/build_library/build_ansible/command_plugins/docs_build.py#L75-L76 definitely needs some update for ansible 3
• we may need something like make webdocs ANSIBLE=2.10;; make webdocs ANSIBLE=3 ;; make coredocs

documenting use of C(. . . )

• https://github.com/ansible/ansible/pull/73312

open floor

• we will have a supplemental meeting Thursday at 11am ET /16:00 UTC to discuss https://github.com/ansible-community/antsibull/pull/238

Actions

• [x] @abadger1999 to figure out how to implement make webdocs ANSIBLE=2.10;; make webdocs ANSIBLE=3 ;; make coredocs and report back later this week
• [x] @acozine to clear the docs backports queue

Logs

Minutes: https://meetbot.fedoraproject.org/ansible-docs/2021-01-26/documentation_working_group_aka_dawgs.2021-01-26-16.02.html Minutes (text): https://meetbot.fedoraproject.org/ansible-docs/2021-01-26/documentation_working_group_aka_dawgs.2021-01-26-16.02.txt Log: https://meetbot.fedoraproject.org/ansible-docs/2021-01-26/documentation_working_group_aka_dawgs.2021-01-26-16.02.log.html

[felixfontein]

• [x] Explicitly decide and document that C(...) should always be used for code snippets. (Context: https://github.com/ansible-collections/ansible.utils/pull/32#discussion_r560490351)

[samccann]

2021-02-02

Index pages for the Core/Package Docsite Split

• https://hackmd.io/mvjYig49R5SQbNHzsd5jfQ?view#Two-Approaches-to-Split-Docs
• AGREED - we will use the 2-index approach with symlink to index.rst to avoid a redirect.

backports status

• https://github.com/ansible/ansible/pulls?q=is%3Apr+is%3Aopen+label%3Adocs+label%3Abackport
• developer guide could use more detail, more updates - explore ways to encourage adding docs with new features and/or expanding existing developer docs

Actions

• [x] @samccann to do a build time simlink from foo_index.rst to index.rst for the 2 index option to eliminate the need for a redirect
• [x] @samccann to see where intersphinx sends me on each site (aka potentially popping to the wrong site)
• [x] @acozine to audit internal links to excluded pages on Core site
• [x] @samccann work with abadger1999 to determine how this works with Ansible package 3.x build out of stable-2.10 and the ability to continue publishing Ansible 2.10 docs for some time to come.

Logs

Minutes: https://meetbot.fedoraproject.org/ansible-docs/2021-02-02/docs_working_group_aka_dawgs.2021-02-02-16.01.html Minutes (text): https://meetbot.fedoraproject.org/ansible-docs/2021-02-02/docs_working_group_aka_dawgs.2021-02-02-16.01.txt Log: https://meetbot.fedoraproject.org/ansible-docs/2021-02-02/docs_working_group_aka_dawgs.2021-02-02-16.01.log.html

[samccann]

2021-02-09

opening chatter

• https://github.com/ansible/community/issues/579#issuecomment-771953772

new landing pages!

• https://docs.ansible.com/

docsite split update

• https://hackmd.io/mvjYig49R5SQbNHzsd5jfQ?both#Release-management-with-automated-docs-build
• https://hackmd.io/mvjYig49R5SQbNHzsd5jfQ?both#Solution is an attempt at ways to solve this
• https://github.com/ansible/ansible/pull/73421
• https://github.com/ansible/ansible/pull/73421 | open, created 2021-01-29T20:21:23Z by samccann: [WIP] Create separate core docs using 2 index files [WIP,affects_2.11,docs,needs_ci,needs_rebase,support:core,test]
• three docs scenarios we have to build
• scenario 1: all the docs: ansible-2.10 docs. No equivalent ansible-base docs go with this.
• scenario2: Ansible 3.x docs (excludes roadmap and porting guides that are targetting ansible-base/core)
• scenario 3: ansible-core 2.11+ docs. (excludes scenario guides and porting guides targetting the ansible package)

open floor

• https://github.com/ansible/ansible/pull/73465 | open, created 2021-02-03T18:57:04Z by abadger: Ansible 4 roadmap [affects_2.11,core_review,docs,has_issue,support:core]
• https://github.com/ansible-community/antsibull/pull/240
• https://github.com/ansible-community/antsibull/pull/240 | open, created 2021-01-17T13:56:50Z by felixfontein: Add breadcrumbs to collection index, plugin indexes etc., and add namespace indexes [bug,enhancement]
• https://github.com/ansible/ansibullbot/pull/1505 | open, created 2021-02-06T14:45:20Z by sommersoft: [WIP] Classify/Label PRs That Are Docs Only
• https://github.com/ansible-community/antsibull/pull/248 | open, created 2021-01-30T20:51:25Z by felixfontein: Support object (role, playbook) announcements in combined changelog

Logs

Minutes: https://meetbot-raw.fedoraproject.org/ansible-docs/2021-02-09/docs_working_group_aka_dawgs.2021-02-09-16.00.html Minutes (text): https://meetbot-raw.fedoraproject.org/ansible-docs/2021-02-09/docs_working_group_aka_dawgs.2021-02-09-16.00.txt Log: https://meetbot-raw.fedoraproject.org/ansible-docs/2021-02-09/docs_working_group_aka_dawgs.2021-02-09-16.00.log.html

[samccann]

2021-02-16

Ansible 3 release and docsite split

• if push come to shove, we can build Ansible 3 from a private branch w/ the pr backported to stable 2.10 (if we can't get reviews in time to merge into stable-2.10)
• • may not be able to merge the backport to stable-2.10 as it is frozen due to pending release

future of devel documentation

• docs.ansible.com/ansible-core/devel/ will be what the current nightly build produces after the docsite split. It will not include scenario or network guides
• https://github.com/bcoca/acd/blob/devel/generate_acd.yml <= can be made trivial 'run this playbook'
• https://ansible-community.github.io/nightly-builds/
• :+1: goal for /ansible/devel/ docs is to include the devel branch of ansible-core, plus the most recent versions in Galaxy of all included collections for the next ansible package release

PR/issue labels: https://github.com/ansible/ansibullbot/pull/1505

• https://github.com/ansible/ansibullbot/pull/1505 | open, created 2021-02-06T14:45:20Z by sommersoft: [WIP] Classify/Label PRs That Are Docs Only
• • example of collection that has docs in docs folder - https://github.com/cyberark/ansible-security-automation-collection/tree/master/docs - this displays today on Automation Hub
• :+1: acozine to add a docs_only label

open floor

• https://github.com/ansible/ansible/pull/73615 | open, created 2021-02-15T17:09:20Z by dmsimard: Update 2.10 porting guide to include module index [affects_2.11,core_review,docs,needs_triage,small_patch,support:core]

Actions

• [x] @- samccann to fix CI errors by using cp instead of ln and finish other feeback so pr can be merged to devel today
• [x] @- turn nightly build to core docs once PR is merged into devel
• [x] @samccann - post last week's meeting minutes on the dawgs agenda
• [x] @samccann acozine - find out where the /docs folder is in AH roadmap etc

Logs

Minutes: https://meetbot.fedoraproject.org/ansible-docs/2021-02-16/docs_working_group_aka_dawgs.2021-02-16-16.00.html Minutes (text): https://meetbot.fedoraproject.org/ansible-docs/2021-02-16/docs_working_group_aka_dawgs.2021-02-16-16.00.txt Log: https://meetbot.fedoraproject.org/ansible-docs/2021-02-16/docs_working_group_aka_dawgs.2021-02-16-16.00.log.html

[felixfontein]

• [x] @tadeboro mentioned that users are confused that docs.ansible.com does not show the latest docs for collections released on galaxy. So maybe the community collections should have docsites which also show docs for the latest collection releases? (Cross-post: https://github.com/ansible/community/issues/539#issuecomment-778847740)

[samccann]

2021-02-23

documentation for filter and test plugins

• filter/test plugin documentation is delayed until ansible-core-2.12

semantic markup proposal

• https://github.com/ansible/proposals/issues/68

open floor

• https://github.com/ansible-community/ansible-build-data/blob/main/3/ansible-3.build <= easy way to answer all 'is it in a.3.0 questions'

Logs

Minutes: https://meetbot.fedoraproject.org/ansible-docs/2021-02-23/docs_working_group_aka_dawgs.2021-02-23-16.01.html Minutes (text): https://meetbot.fedoraproject.org/ansible-docs/2021-02-23/docs_working_group_aka_dawgs.2021-02-23-16.01.txt Log: https://meetbot.fedoraproject.org/ansible-docs/2021-02-23/docs_working_group_aka_dawgs.2021-02-23-16.01.log.html

[samccann]

2021-03-02

devel docs for the community package

• :+1: develdocs for /ansible/ always showingdevel` branch of ansible-core plus most recent Galaxy versions of included collections
• we chose the simplest approach for the Ansible devel docs

collections /docs/ folder

• TBD what we can do with the collection /docs/ folder as some collections use .md there, others use .rst to repeat module level docs, neither of which work with docs.ansible.com today
• we would need some script to check for properly formatted labels at the collection rep o CI itself
• we'd also need 'something' to create unique labels once they are brought into ansible docs build (e.g. prepend collection name)

PR 73676

• https://github.com/ansible/ansible/pull/73676

PR 73170

• https://github.com/ansible/ansible/pull/73170
• https://github.com/ansible/ansible/pull/73170 | open, created 2021-01-09T22:11:24Z by felixfontein: Use antsibull sphinx extension [affects_2.11,core_review,docs,support:core,test]

open floor

• link to docs survey blog - https://emeraldreverie.org/2021/02/23/docs-survey-2020-results/
• https://github.com/ansible/ansible/pull/73637) | open, created 2021-02-17T17:39:23Z by acozine: WIP: Backport of Split Ansible docs from core docs (#73616) [WIP,affects_2.10,backport,ci_verified,docs,needs_triage,stale_ci,support:core,test]
• Contributors Summit next week https://hackmd.io/uZDSLOOdS1Kx0xfZVIATmQ

Logs

Minutes: https://meetbot.fedoraproject.org/ansible-docs/2021-03-02/docs_working_group_aka_dawgs.2021-03-02-16.01.html Minutes (text): https://meetbot.fedoraproject.org/ansible-docs/2021-03-02/docs_working_group_aka_dawgs.2021-03-02-16.01.txt Log: https://meetbot.fedoraproject.org/ansible-docs/2021-03-02/docs_working_group_aka_dawgs.2021-03-02-16.01.log.html

[felixfontein]

In today's community meeting (https://github.com/ansible/community/issues/539#issuecomment-785354123), we decided that /devel/ should not include pre-releases of collections. That saves the DaWGs meeting from also discussing that ;-)

[felixfontein]

• [x] ansible/ansible#73676: improve infoblox scenario guide
• [x] ansible/ansible#73170: use antsibull sphinx extension instead of vendored sphinx plugins and CSS

[samccann]

2021-03-16

collection /docs/ folder usage

• https://github.com/ansible-community/antsibull/pull/255 | open, created 2021-03-06T19:52:36Z by felixfontein: [WIP] Allow collections to add RST files
• https://ansible.fontein.de/collections/felixfontein/tools/
• https://github.com/felixfontein/ansible-tools/compare/docs#diff-1581b6b05d6f713e6fa7078d9ed1cd1202ac5842aff67635839e3faf7276c54f
• :+1: designate a subdirectory of the collection /docs/ folder for rst docs and publish them to docs.ansible.com

open floor

• https://github.com/ansible-collections/community.mysql/pull/112/files

Logs

Minutes: https://meetbot.fedoraproject.org/ansible-docs/2021-03-16/docs_working_group_aka_dawgs.2021-03-16-16.02.html Minutes (text): https://meetbot.fedoraproject.org/ansible-docs/2021-03-16/docs_working_group_aka_dawgs.2021-03-16-16.02.txt Log: https://meetbot.fedoraproject.org/ansible-docs/2021-03-16/docs_working_group_aka_dawgs.2021-03-16-16.02.log.html

[felixfontein]

• [x] ansible-community/antsibull#255 WIP for using collection docs/docsite/rst/ on docs.ansible.com

[samccann]

2021-03-23

meeting time for summer

• :+1: we will move this meeting one hour earlier starting next week

update on devel docs

• options for a Devel version of ansible-core and the latest collection versions https://hackmd.io/E5a0dw0tTDCteQVVk4VvJw?both#Development-of-ansible-core-and-latest-of-collections
• next step is to implement this idea

breadcrumbs

• https://github.com/ansible-community/antsibull/pull/240 | closed, created 2021-01-17T13:56:50Z by felixfontein: Add breadcrumbs to collection index, plugin indexes etc., and add namespace indexes [bug,enhancement]

Actions

• [x] @acozine to change the UTC time schedule for the DaWGs meeting

Logs

Minutes: https://meetbot.fedoraproject.org/ansible-docs/2021-03-23/docs_working_group_aka_dawgs.2021-03-23-16.00.html Minutes (text): https://meetbot.fedoraproject.org/ansible-docs/2021-03-23/docs_working_group_aka_dawgs.2021-03-23-16.00.txt Log: https://meetbot.fedoraproject.org/ansible-docs/2021-03-23/docs_working_group_aka_dawgs.2021-03-23-16.00.log.html

[abadger]

I'm double booked this week, so I am posting a little information early in case I'm not watching the meeting when it's discussed

* [ ]  Meeting time  - do we adjust it 30 min earlier?

I can make a meeting 30 minutes to one hour earlier (until Daylight Saving Time shifts again :-)

* [ ]  Ansible (package) devel docs - how can we get the latest collection versions into docs.ansible.com/ansible/devel  (excluding prereleased versions)?

Does this option and implementation look like what we want?

https://hackmd.io/E5a0dw0tTDCteQVVk4VvJw?both#Development-of-ansible-core-and-latest-of-collections

* [ ]  docs for filter/test plugins

It would be great if we can have input on what the structure of this looks like. One of the problems that I found with the current plugin doc data structures is that the names don't follow any common standards. I've addressed that in antsibull-docs by writing a schema which normalizes all of the names prior to giving the data to the rest of the program but it would be better if these were standardized in the specification.

[samccann]

2021-03-30

opening chatter

• role argspec not quite ready for documentation generation. Still needs examples, and ansible-doc work potentially

rules for the docsite_pr label on GitHub

• this explains the options for the docsite_pr label - https://github.com/ansible/community/issues/579#issuecomment-809823241
• as reviewers, we should assume the PR creator may not be familiar with git etc and keep edits within 'suggested edits'
• :+1: the label must be applied when Edit on GitHub is clicked from docs.ansible.com pages and can also be applied when it's clicked directly from within the GitHub site. If applying the label to both is the easy way to implement this feature, let's do that. If "apply to both situations" is harder to implement, let's skip the second situation.

package devel docs

• tracking issue https://github.com/ansible-community/antsibull/issues/54
• • published devel with Ansible 4 collection list and it works
• https://docs.ansible.com/ansible/devel/collections/
• still to come - we need a way to pull the most recent collection versions from galaxy to publish to devel

meeting time follow-up

• https://github.com/ansible/community/blob/main/meetings/ical/docs.ics

collection /docs/ folder

• collection /docs folder proposal - https://github.com/ansible-community/antsibull/issues/242
• we agreed to use option A in that proposal. Next step is to delve further into what this would look like, a roadmap of tasks, and/or a sample collection (preferably with a transfer of docs out of the Scenario Guides section).
• a collection /docs folder can have multiple .rst files and some local index. And the technical details is how do we inject all this into docs.ansible.com

open floor

• the breadcrumbs feature for collections was disabled due to excessive memory use
• f we want to reenable breadcrumbs, we can ask if the jenkins workers can be given more RAM or we can redesign the implementation to not use the sphinx breadcrumb feature
• ticket to add a config option to enable collection breadcrumbs: https://github.com/ansible-community/antsibull/issues/267
• we could pass CPUs=1 in the jenkins buld script without reconfiguring the jenkins workers, maybe on the nightly build?
• if we test this, we need to use antsibull==0.29.0 as most recent has breadcrumbs disabled

Actions

• [x] @acozine to regenerate the meetings calendar for ansible/community
• [x] @samccann acozine to review logs/minutes and update docs proposal issue accordingly

Logs

Minutes: https://meetbot-raw.fedoraproject.org/ansible-docs/2021-03-30/docs_working_group_aka_dawgs.2021-03-30-15.00.html Minutes (text): https://meetbot-raw.fedoraproject.org/ansible-docs/2021-03-30/docs_working_group_aka_dawgs.2021-03-30-15.00.txt Log: https://meetbot-raw.fedoraproject.org/ansible-docs/2021-03-30/docs_working_group_aka_dawgs.2021-03-30-15.00.log.html

[sommersoft]

Proposal For Agenda Item For 2021-03-30

During review of https://github.com/ansible/ansibullbot/pull/1537 to apply docsite_pr label, a question of desired intent/behavior came up.

Would like to ask the DaWGs if the docsite_pr should be applied:

1. Only when Edit on GitHub is clicked from docs.ansible.com pages.

   • Ansibullbot does/will utilize +label: docsite_pr in any PR comment. This label command is included with the URL via Edit on GitHub links from docs.ansible.com.

2. When Edit on GitHub is clicked from both docs.ansible.com, and directly from within the GitHub site.

   • Ansibullbot will utilize both +label: docsite_pr in PR comments, as well the metadata from a PR's commits via the GitHub API.

_Reminder: the docsite_pr label description is "This PR is created from documentation using the "Edit on GitHub" link."_

[samccann]

@sommersoft just so it's not lost in meeting minutes, the DaWGs meeting just now agreed the label must be applied when Edit on GitHub is clicked from docs.ansible.com pages and can also be applied when it's clicked directly from within the GitHub site. If applying the label to both is the easy way to implement this feature, let's do that. If "apply to both situations" is harder to implement, let's skip the second situation.

[samccann]

2021-04-06

PR and issue counts keep growing

• :+1: we will try a Docs PR Half-Day on April 20th, starting one hour before the usual DaWGs meeting, lasting 4 hours

updates on long-running topics

• https://github.com/ansible/ansible/pull/73707
• /docs folder work needs a volunteer to do the coding
• for https://github.com/ansible/ansible/pull/73707 - can we have partial instead of yes as a support option? And not doing orphan status until discussed/decided in the community meeting
• examples of the docs folder in action https://github.com/ansible-community/antsibull/pull/255
• other next steps on collections /docs/ folder work: draft some community docs describing how to use the feature, make codecov happy if we can

open floor

• we need to go back to docs survey results to see what might be next on our plates
• next steps - get breadcrumbs back up and running, get collection docs going, then try to clear the backlog of PRs and issues
• comments/reviews on PRs always welcome! It helps move them to completion and merging

Actions

• [x] @acozine to create a PR that moves a Scenario Guide into a collection and uses felixfontein's PR https://github.com/ansible-community/antsibull/pull/255

Logs

Minutes: https://meetbot.fedoraproject.org/ansible-docs/2021-04-06/docs_working_group_aka_dawgs.2021-04-06-15.01.html Minutes (text): https://meetbot.fedoraproject.org/ansible-docs/2021-04-06/docs_working_group_aka_dawgs.2021-04-06-15.01.txt Log: https://meetbot.fedoraproject.org/ansible-docs/2021-04-06/docs_working_group_aka_dawgs.2021-04-06-15.01.log.html

[samccann]

2021-04-13

Reminder of next week's PR Review Day

• next Tuesday April 20 we will have a Docs PR Review Day
• easy way to find docs PRs: https://github.com/ansible/ansible/pulls?q=is%3Apr+is%3Aopen+label%3Adocs
• :+1: Mini Docs PR Day to start at 10AM Eastern time and last 4 hours on April 20

breadcrumbs

• the PR is A command line argument to turn breadcrumbs on. We'll have to leave it off in production until the jenkins builders are upgraded with more memory. Once they add more memory, you'll be able to test that it has fixed the problem.

open floor

• https://docs.ansible.com/ansible-core/devel/
• core docs have a new look to make it distinct from Ansible pkg docs - https://docs.ansible.com/ansible-core/devel/
• change to core docs came from https://github.com/ansible/ansible/pull/74200/commits

Actions

• [x] @samccann add docs PR day to bullhorn
• [x] @abadger1999 to start work on devel for Ansible package docs (some coding, not PoC yet)
• [x] @acozine to request more resources for Jenkins

Logs

Minutes: https://meetbot.fedoraproject.org/ansible-docs/2021-04-13/docs_working_group_aka_dawgs.2021-04-13-15.00.html Minutes (text): https://meetbot.fedoraproject.org/ansible-docs/2021-04-13/docs_working_group_aka_dawgs.2021-04-13-15.00.txt Log: https://meetbot.fedoraproject.org/ansible-docs/2021-04-13/docs_working_group_aka_dawgs.2021-04-13-15.00.log.html

[samccann]

2021-04-20 - DaWGs Documentation mini PR day!

Join us on #ansible-docs on IRC for a 4 hour PR review day, starting at 10AM ET.

[samccann]

2021-04-27

opening chatter

• ansible-core 2.11 was released yesterday (April 26)
• Ansible 2.9.21rc1 and 2.10.9rc1 are being cut today
• last week's DaWGs Mini Docs PR Day reviewed and merged or close 12 PRs, thanks to all who participated!
• core docs are now at https://docs.ansible.com/ansible-core/devel/index.html

versions and maintenance

• version-switcher for /ansible/ docs now only shows devel, latest (which is 3) and 2.9
• once Ansible 4 releases, it will become latest and Ansibl 3 docs will be EOL
• if a maintenance team steps forward for Ansible 3, we can add 3 to the mix, but maintainers will need to maintain docs (with backports) as well as code

Sphinx upgrade

• WIP PR to upgrade the Sphinx version is open: https://github.com/ansible/ansible/pull/74372
• if any folks have spare time this week, please test the latest Sphinx version with our docs
• https://www.sphinx-doc.org/en/master/
• :+1: we'd rather risk breakages with updates to Sphinx than face the problems of pinning to a known older version
• Sphinx has a channel called sphinx-doc here on freenode IRC, maybe one of the DaWGs can join that and keep tabs on upcoming changes

ansible Sphinx theme

• WIP PR: https://github.com/ansible/ansible/pull/74318
• the ansible theme is pretty close to what we need, but have some requests in for changes to match our current look and feel and to support ansible-core docs with theme changes
• theme changes for ansible-core introduced in https://github.com/ansible/ansible/pull/74356; current ansible-core docs are published as https://docs.ansible.com/ansible-core/devel/
• core theme changes support a different look so readers know they are not on the Ansible (package) docsite

searching and sitemaps for the ansible-core docs

• https://packages.gentoo.org/packages/search?q=ansible
• need to keep this discussion open - what are the distros doing with ansible vs ansible core etc. Gentoo seems to have both for example

Actions

• [x] @samccann to test sphinx 4.x beta as it has 'breaking changes' warning on it

Logs

Minutes: https://meetbot.fedoraproject.org/ansible-docs/2021-04-27/docs_working_group_aka_dawgs.2021-04-27-15.01.html Minutes (text): https://meetbot.fedoraproject.org/ansible-docs/2021-04-27/docs_working_group_aka_dawgs.2021-04-27-15.01.txt Log: https://meetbot.fedoraproject.org/ansible-docs/2021-04-27/docs_working_group_aka_dawgs.2021-04-27-15.01.log.html

[acozine]

Last-minute agenda additions:

• [x] retrospective on the Mini Docs PR Day
• [x] discussion about Sphinx upgrade (see WIP PR https://github.com/ansible/ansible/pull/74372)
• [x] searching and sitemap for /ansible-core/ documentation

[samccann]

2021-05-04

opening chatter

• we are still backporting docs fixes to the 2.11 branch to prepare for Ansible 4
• please don't open any one-PR backports, since we do them in batches and merging one out of order can create merge conflict headaches

breadcrumbs update

• can we avoid the "run one process per detected CPU" default behavior in sphinx by setting some env variable?
• if we run into blockers, we can reach out to the Sphinx maintainers on the Write the Docs Slack instance

/docs/ folder in collections

• https://github.com/ansible-collections/community.docker/compare/main...felixfontein:scenario-guide is an example of a scenario guide within community.docker (for POC)
• consider stubbing out those toc pages for scenarios for a release, and add links in them to where the individual scenario guides live within the collection index
• since this would just add docs files to a collection, we could implement this in the 4.x timeline

Actions

• [x] @samccann to test breadcrumbs again with new jenkins job
• [x] @samccann to find out how many hits we get on scenario toc pages like cloud_guides.html

Logs

Minutes: https://meetbot.fedoraproject.org/ansible-docs/2021-05-04/docs_working_group_aka_dawgs.2021-05-04-15.02.html Minutes (text): https://meetbot.fedoraproject.org/ansible-docs/2021-05-04/docs_working_group_aka_dawgs.2021-05-04-15.02.txt Log: https://meetbot.fedoraproject.org/ansible-docs/2021-05-04/docs_working_group_aka_dawgs.2021-05-04-15.02.log.html

[samccann]

2021-05-11

copyright notices

• https://github.com/ansible/ansible/pull/74643
• updating copyright on docs.ansible.com to drop year/date and credit Ansible project contributors see https://github.com/ansible/ansible/pull/74643/files

update on traffic to existing Scenario Guide TOCs

• https://docs.ansible.com/ansible/latest/scenario_guides/cloud_guides.html gets 1.2k visitors a month. That is 0.2% of all docs traffic
• and 6% of all scenario guide traffic
• https://docs.ansible.com/ansible/latest/scenario_guides/
• :+1: stub out individual scenario guides to point to their new locations as they are moved. Add the stubs to a robots.txt file on the server so google ignores them

updates on long-running topics

• • breadcrumbs testing seems to be good. abadger to release and updated antsibull that re-enables it
• making some progress on testing the move of a scenario guide to a collection. All still WIP
• the moved guides will need a specific anchor like .. _ansible_collections.community.docker.docsite.scenario_guide:

options for including rst documentation in the collection index pages

• https://github.com/felixfontein/community.docker/blob/scenario-guide/docs/docsite/index.yml produces https://ansible.fontein.de/collections/community/docker/
• we are looking for a way to inject rst into the existing autogenerated collection index page.
• so the index.yml defines what those additional materials should be called on the existing index page, under that collection.
• :+1: use felixfontein's existing PR for collections additional docs from the /docs/ folder, with one small change - name the top-level YAML file extra-docs.yml

open floor

• https://github.com/ansible/ansible/pull/74245
• https://github.com/ansible/ansible/pull/74245 breaks html docs for set_fact and user. We should consider reverting it
• https://github.com/ansible/ansible/issues/73995 relates to this problem
• example of broken link - https://docs.ansible.com/ansible/devel/collections/ansible/builtin/set_fact_module.html

Actions

• [x] @acozine to update AWS collection PR to match (and fix its anchors)
• [x] @acozine to summarize the problems with https://github.com/ansible/ansible/pull/74245 in a GitHub issue

Logs

Minutes: https://meetbot.fedoraproject.org/ansible-docs/2021-05-11/docs_working_group_aka_dawgs.2021-05-11-15.00.html Minutes (text): https://meetbot.fedoraproject.org/ansible-docs/2021-05-11/docs_working_group_aka_dawgs.2021-05-11-15.00.txt Log: https://meetbot.fedoraproject.org/ansible-docs/2021-05-11/docs_working_group_aka_dawgs.2021-05-11-15.00.log.html

[samccann]

2021-05-18

version-specific links in docs and PR 74245

• see https://github.com/ansible/ansible/issues/74688 for a quick summary of some aspects of this issue
• ansible-doc in 2.11 doesn't understand L() relative links at all so will return a relative path that is 404 for a user
• https://docs.ansible.com/ansible/become.html will not work in any version
• there are a scattering of error messages within module python code that have hard-coded urls to latest. Some of these have been changes to use relative links base on these PRs
• ansible-doc in 2.11 doesn't understand L() relative links at all so will return a relative path that is 404 for a user
• we have a scattering of errorr messages within module python code that uses the relative link function. This is broken in 2.11 since ansible/2.11 does not exist anymore.
• :+1: we want any links to go to /ansible/ not /ansible-core/
• if we revert PR 74245 and leave PR 74665, then backport 74665, that should fix the error message output
• since also AH and antsibull-doc need to implement the compatible solutions, any solution needs to be discussed and agreed by all three parties first
• :+1: 1. add a redirect for 2.11 => latest as a temporary fix, 2. revert 74245, 3. backport 74665 to 2.11 when we can (remembering that it may take some time to propagate, since folks don't upgrade quickly), 4. create an issue that covers all the aspects of Version-Sensitive Docs Links before we try to fix it again

Logs

Minutes: https://meetbot-raw.fedoraproject.org/ansible-docs/2021-05-18/documentation_working_group_aka_dawgs.2021-05-18-15.00.html Minutes (text): https://meetbot-raw.fedoraproject.org/ansible-docs/2021-05-18/documentation_working_group_aka_dawgs.2021-05-18-15.00.txt Log: https://meetbot-raw.fedoraproject.org/ansible-docs/2021-05-18/documentation_working_group_aka_dawgs.2021-05-18-15.00.log.html

[acozine]

• [x] Scenario Guides move PRs: https://github.com/ansible-collections/amazon.aws/pull/362 https://github.com/ansible/ansible/pull/74704
• [x] Issue summarizing the problems with ansible/ansible#74245: https://github.com/ansible/ansible/issues/74688
• [x] Sphinx theme for Ansible: https://github.com/ansible/ansible/pull/74318

[samccann]

2021-05-25

opening chatter

• we now have an #ansible-docs channel on irc.libera.chat
• pending the community decision tomorrow, we may move to libera for next week's meeting. We will post details here when that decision is made
• https://libera.chat/guides/registration

Jinja2 upgrade issue

• proposed plan for preventing dependency surprises: pin dependencies to latest known good versions in docs/docsite/requirements.txt, schedule quarterly reviews in DaWGs where we "unleash" the versions and fix any issues that come up
• and then pin to the new tested versions so we don't have a docs outage like we had last week
• Pros and cons of using the last tested version: Pro: We know that the docs won't start mysteriously failing for a reason unrelated to any updates we make. Con: System packagers and other people building docs in a controlled environment could have difficulty building the docs because they could be standardizing on a newer version than we have pinned.
• VOTE: revise previous proposal to implement a "two-file solution" so users can choose to install known-good versions or any version
• :+1: we will include both an unpinned requirements.txt file and a pinned known-good-versions.txt (exact name of the second file TBD) in docs/docsite for visibility and flexibility, then use the pinned file in Jenkins to avoid surprises

collection docs stuff

• breadcrumbs work is done, breadcrumbs are live on the site, and the build is creating them reliably
• collections "extra docs" will be added this week
• :+1: https://github.com/ansible-community/antsibull/pull/255 is ready to merge

Logs

Minutes: https://meetbot.fedoraproject.org/ansible-docs/2021-05-25/docs_working_group_aka_dawgs.2021-05-25-15.08.html Minutes (text): https://meetbot.fedoraproject.org/ansible-docs/2021-05-25/docs_working_group_aka_dawgs.2021-05-25-15.08.txt Log: https://meetbot.fedoraproject.org/ansible-docs/2021-05-25/docs_working_group_aka_dawgs.2021-05-25-15.08.log.html

[felixfontein]

• [x] https://github.com/ansible-community/antsibull/pull/255 Extra docs for collections
• [x] https://github.com/ansible-community/antsibull/pull/272 Generate role documentation

[samccann]

2021-06-01

opening chatter

• Contributors Summit is next week https://hackmd.io/0lOyfyEpQ1uKimC4mD6xdw 07:00 - 15:00 UTC

Contributors' Summit

• https://whena.re/ansible-community is helpful to visualize timezones :)

devel docs for hte package

• details on the ideas are at https://hackmd.io/E5a0dw0tTDCteQVVk4VvJw
• https://github.com/ansible-community/antsibull/issues/54
• tracking issue for antsibull work needed - https://github.com/ansible-community/antsibull/issues/54
• goal is to pull the most recent version on galaxy for each included collection to document devel for Ansible the package

template for using collection /docs/ folder

• https://docs.ansible.com/ansible/latest/dev_guide/developing_collections_structure.html#docs-directory
• the PR for this is merged - https://github.com/ansible-community/antsibull/pull/255
• first candidates to exercise this may be community.docker, community.crypto and community.general
• https://github.com/ansible/ansible/pull/74736
• remove docker docs pr is https://github.com/ansible/ansible/pull/74736
• so as soon as we have a package release that includes the version of community.docker that has those docs, we can merge

open floor

• filter docs PR for community.general requires a change to either antsibull or the ansible syntax highlighter
• https://github.com/ansible-collections/community.general/pull/2680/files
• An Ansible Beginner's Guide to Filters might be a good addition to the dev-focused filter docs

Actions

• [x] @abadger1999 to take some time this week if possible to delve further on this one
• [x] @document how to use the collection /docs folder (.md or .rst) at https://docs.ansible.com/ansible/latest/dev_guide/developing_collections_structure.html#docs-directory

Logs

Minutes: https://meetbot.fedoraproject.org/ansible-docs/2021-06-01/ansible_documentation_working_group_aka_dawgs_meeting.2021-06-01-15.01.html Minutes (text): https://meetbot.fedoraproject.org/ansible-docs/2021-06-01/ansible_documentation_working_group_aka_dawgs_meeting.2021-06-01-15.01.txt Log: https://meetbot.fedoraproject.org/ansible-docs/2021-06-01/ansible_documentation_working_group_aka_dawgs_meeting.2021-06-01-15.01.log.html

[samccann]

2021-06-08

collection extra docs and Ansible 4.1 release . . .

• community.crypto, community.general and community.docker have docs/docsite folders
• these should show up in their new place on docs.ansible.com/ansible after 4.1.0 releases (aka collection must be in the Ansible package before the docs will show up)
• see https://docs.ansible.com/ansible/devel/dev_guide/developing_collections_structure.html#docs-directory for details on how to move scenario guides to a collection repo
• and see https://github.com/ansible-collections/amazon.aws/pull/362 for an example of a moved scenario guide
• use antsibull-lint collection-docs for some first sanity checks

Ansible Sphinx theme

• ansible-theme should be mergable soon. One final check on staging

semantic markup

• https://github.com/ansible/ansible/pull/73137
• discussion from https://github.com/ansible/ansible/pull/73137
• considering leaving M() as is, and adding P(name#type) for all plugins e.g. P(ansible.builtin.apt#module) etc

open floor

• https://hackmd.io/lAJfWYrlT3Gg1VXYGBoZtA
• we will be trying to create 'personas' and how each different ansible docs reader is looking for info in our docs. More to come
• agenda items can be added to https://github.com/ansible/community/issues/579 at any time by anyone

Logs

Minutes: https://meetbot.fedoraproject.org/ansible-docs/2021-06-08/docs_working_group_aka_dawgs.2021-06-08-15.00.html Minutes (text): https://meetbot.fedoraproject.org/ansible-docs/2021-06-08/docs_working_group_aka_dawgs.2021-06-08-15.00.txt Log: https://meetbot.fedoraproject.org/ansible-docs/2021-06-08/docs_working_group_aka_dawgs.2021-06-08-15.00.log.html

[felixfontein]

• [x] https://github.com/ansible/ansible/pull/74736 complete the move of the docker scenario guide to community.docker

[samccann]

2021-06-15

moving docker scenario guide

• https://github.com/ansible/ansible/pull/74736
• docker PR to remove old scenario guide and put in a stub https://github.com/ansible/ansible/pull/74736/files
• depends on this devel PR to work on devel - https://github.com/ansible/ansible/pull/74987

updating collection version list for devel docs

• https://github.com/ansible/ansible/pull/74987/files
• https://github.com/ansible/ansible/pull/74987/files
• the workaround will ensure the collections section of the devel docs will be identical to the collections section of latest docs for now. Until we have real 'devel' collections docs
• https://github.com/ansible-community/antsibull/pull/282
• https://github.com/ansible/ansible/pull/74988
• reviews welcome on https://github.com/ansible-community/antsibull/pull/282 and https://github.com/ansible/ansible/pull/74988
• related issue is https://github.com/ansible-community/antsibull/issues/54
• reviews welcome on https://github.com/ansible/ansible/pull/74914
• reviews also welcome on https://github.com/ansible/ansible/pull/74963 btw which adds documentation capabilities for filter and test docs
• the two PRs above expand the range of the generated technical docs (by extending config documentation and documenting filter and test plugins)

semantic markup

• just fyi - devel docs get approx 4% of the traffic vs /latest/ docs and /ansible-core/ gets approx 1%
• https://github.com/ansible/ansible/pull/74937
• https://github.com/ansible-community/antsibull/pull/281
• https://github.com/ansible-collections/community.dns/pull/23
• https://github.com/ansible/ansible/pull/73137
• related PRs https://github.com/ansible/ansible/pull/74937 https://github.com/ansible-community/antsibull/pull/281 https://github.com/ansible-collections/community.dns/pull/23
• key=value pair rendering - IBM style guide suggests monospace
• older discussions on this topic https://github.com/ansible/community/issues/521#issuecomment-739263018 and https://meetbot.fedoraproject.org/ansible-docs/2020-12-15/dawgs_aka_docs_working_group.2020-12-15-16.01.log.html (search for value)

Actions

• [x] @- review these rendering options to vote next week:
  1. I(option=value) https://dmsimard.com/files/docsite/1/collections/ansible/builtin/lineinfile_module.html
  2. C(option=value) https://dmsimard.com/files/docsite/2/collections/ansible/builtin/lineinfile_module.html
  3. I(option)=C(value) https://dmsimard.com/files/docsite/3/collections/ansible/builtin/lineinfile_module.html
  4. I(option=)C(value) https://dmsimard.com/files/docsite/4/collections/ansible/builtin/lineinfile_module.html
  5. B(option)=C(value) https://dmsimard.com/files/docsite/5/collections/ansible/builtin/lineinfile_module.html

Logs

Minutes: https://meetbot.fedoraproject.org/ansible-docs/2021-06-15/documentation_working_group_aka_dawgs.2021-06-15-15.01.html Minutes (text): https://meetbot.fedoraproject.org/ansible-docs/2021-06-15/documentation_working_group_aka_dawgs.2021-06-15-15.01.txt Log: https://meetbot.fedoraproject.org/ansible-docs/2021-06-15/documentation_working_group_aka_dawgs.2021-06-15-15.01.log.html

[felixfontein]

• [x] fix devel docs: https://github.com/ansible/ansible/pull/74987
• [x] properly implement devel docs: https://github.com/ansible-community/antsibull/pull/282 and https://github.com/ansible/ansible/pull/74988
• [x] semantic markup WIPs:
  • ansible-doc: https://github.com/ansible/ansible/pull/74937
  • antsibull: https://github.com/ansible-community/antsibull/pull/281
  • collection example: https://github.com/ansible-collections/community.dns/pull/23

[samccann]

2021-06-22

semantic markup

• summary issue: https://github.com/ansible/ansible/issues/75054
• https://github.com/ansible/ansible/pull/73137
• the proposed semantic markup is O(k) for option names, O(k=v) for option key/values, V(v) for option values, E(env) for env variables, and P(community.general.foo#lookup) for plugin references
• correction to the vote above: semantic markup macros: O(k) for option names, O(k=v) for option key/values, V(v) for option values, E(env) for env variables, and P(FQCN#plugintype) for plugin references; existing markup macros will remain
• :+1: semantic markup macros: O(k) for option names, O(k=v) for option key/values, V(v) for option values, E(env) for env variables, and P(FQCN#plugintype) for plugin references; existing markup macros will remain
• IBM style guide says parameter names are 'bold monospace' and values are 'monospace' but key-value pairs are monospace only.
• :+1: follow IBM style guide as much as we can with RST for these semantic markup options

open floor

• rendering bold mono might require a custom RST role, which can be achieved by a Sphinx extension (which the antsibull sphinx extension happens to be)

Actions

• [x] @acozine to followup with core, navigator? and galaxy on the proposed new markup options
• [x] @review and merge backport of ansible sphinx theme to 2.11 https://github.com/ansible/ansible/pull/75058
• [x] @abadger1999 to review and (hopefully) merge antsibull PRs 284, 283, 285, and then 282 today.
• [x] @with a new version of antsibull (potentially today?), getting https://github.com/ansible/ansible/pull/75059 (with == 0.7.0 and not >= 0.7.0) merged would be good, as well as getting https://github.com/ansible/ansible/pull/74956 merged (probably first, so it doesn't collect more potential conflicts)

Logs

Minutes: https://meetbot.fedoraproject.org/ansible-docs/2021-06-22/documentation_working_group_aka_dawgs.2021-06-22-15.01.html Minutes (text): https://meetbot.fedoraproject.org/ansible-docs/2021-06-22/documentation_working_group_aka_dawgs.2021-06-22-15.01.txt Log: https://meetbot.fedoraproject.org/ansible-docs/2021-06-22/documentation_working_group_aka_dawgs.2021-06-22-15.01.log.html

[acozine]

Follow up on dependency management:

• [x] pinned and unpinned requirements files: https://github.com/ansible/ansible/pull/74956

[samccann]

2021-06-29

follow up on action items

• no feedback yet on semantic markup from core and galaxy teams
• summary of semantic markup plan https://github.com/ansible/ansible/issues/75054

devel docs update and build EOF/OOM issues

• the sphinx memory problem stems from building breadcrumbs. Workaround if necessary is to disable them again
• modify the ansible.in or ansible-VERSION.deps locally to add more collections from galaxy
• (ansible.in for devel docs. ansible-VERSION.deps for stable docs)

new module documentation fields

• new attributes PR - https://github.com/ansible/ansible/pull/73707
• https://docs.ansible.com/ansible/devel/collections/ansible/builtin/import_playbook_module.html#ansible-collections-ansible-builtin-import-playbook-module
• this PR breaks the docs output since antsibull isn't recognizing these fields yet. But PR owner plans more changes, so need to decide if we wait for that or revert until it's complete
• PR also has no documentation for what it is supporting

open floor

• https://github.com/ansible/ansible/pull/74873
• https://github.com/ansible/ansible/pull/74963/files
• PRs that need input from docs stakeholders: https://github.com/ansible/ansible/pull/74873, https://github.com/ansible/ansible/pull/74963, and possibly https://github.com/ansible/ansible/pull/75116
• agenda items welcome, add a comment to https://github.com/ansible/community/issues/579

Actions

• [ ] @acozine to keep requesting feedback on semantic markup plan, especially about the display of the new options in galaxy-ng and in ansible-doc output"
• [x] @samccann to test local VM with less memory, then with more memory and more collections to see how much each extra GB of ram gets us
• [x] @abadger1999 to find a way to turn of breadcrumbs so we can get the builds working again, esp for today's release
• [x] @acozine to talk to gundalow/Spredzy once we know for sure that memory is our issue this time
• [x] @acozine to follow up on the problems with PR 73707
• [x] @samccann abadger1999 acozine to followup on how we can havea better process in place to stop changes to ansible-doc etc until the full pipeline has agreed to support said changes

Logs

Minutes: https://meetbot.fedoraproject.org/ansible-docs/2021-06-29/docs_working_group_aka_dawgs.2021-06-29-15.01.html Minutes (text): https://meetbot.fedoraproject.org/ansible-docs/2021-06-29/docs_working_group_aka_dawgs.2021-06-29-15.01.txt Log: https://meetbot.fedoraproject.org/ansible-docs/2021-06-29/docs_working_group_aka_dawgs.2021-06-29-15.01.log.html

[samccann]

2021-07-06

docsite builds

• local testing on a VM put 7G too low, but 8G ram worked even when adding a handful more collections that totaled over 1K more plugins
• now asking The Powers That Be for more memory for the Jenkins build that runs it all

action items follow-up

• need to create a tracking document to set out a list of goals for plugin docs so we can evaluate possible solutions against this.
• ansible-core CI does test rst files and builtin plugin docs - https://github.com/ansible/ansible/blob/devel/test/sanity/code-smell/docs-build.py#L33

open floor

• https://github.com/ansible-community/antsibull/pull/272 (role docs) is not blocked by the above though :)
• interesting case are probably roles which have multiple entrypoints, like the ones in sensu.sensu_go (example: https://ansible.fontein.de/collections/sensu/sensu_go/agent_role.html#ansible-collections-sensu-sensu-go-agent-role)

Actions

• [x] @abadger1999 to allow us to turn of breadcrumbs so we can get the docs builds working as an interim fix until we get more Jenkins memory
• [x] @samccann acozine to get a hackmd or something to come up with a list of goals, we can evaluate potential solutions to the problem by how well they meet those goals
• [x] @samccann acozine to review roles output etc from https://github.com/ansible-community/antsibull/pull/272
• [ ] @abadger1999 to also work on the structure of the code for that PR to use parallel pathways

Older Action Items still open

• [ ] @acozine to keep requesting feedback on semantic markup plan, especially about the display of the new options in galaxy-ng and in ansible-doc output"
• [x] @acozine to follow up on the problems with PR 73707

Logs

Minutes: https://meetbot.fedoraproject.org/ansible-docs/2021-07-06/documentation_working_group_aka_dawgs.2021-07-06-15.00.html Minutes (text): https://meetbot.fedoraproject.org/ansible-docs/2021-07-06/documentation_working_group_aka_dawgs.2021-07-06-15.00.txt Log: https://meetbot.fedoraproject.org/ansible-docs/2021-07-06/documentation_working_group_aka_dawgs.2021-07-06-15.00.log.html

[samccann]

2021-07-13

breadcrumbs and memory issues with the production docs build

• https://github.com/ansible-community/antsibull/pull/292
• we can now toggle breadcrumbs on and off
• we also got more memory for the docs build

roles documentation PR

• https://github.com/ansible-community/antsibull/pull/272
• https://github.com/ansible-community/antsibull/pull/272/files#diff-3d3bf4a558c2567fdb54935c5e719bf28a889ddd812ece6d3d777ca42be19e8dR5

Actions

• [x] @samccann to test the devel build with the breadcrumb toggle

Logs

Minutes: https://meetbot.fedoraproject.org/ansible-docs/2021-07-13/docs_working_group_aka_dawgs.2021-07-13-15.01.html Minutes (text): https://meetbot.fedoraproject.org/ansible-docs/2021-07-13/docs_working_group_aka_dawgs.2021-07-13-15.01.txt Log: https://meetbot.fedoraproject.org/ansible-docs/2021-07-13/docs_working_group_aka_dawgs.2021-07-13-15.01.log.html

[samccann]

2021-07-20

redirects on the docsite

• community.docker is in Ansible 4 and the version with the moved scenario guide is part of latest so a backport of the stub page is good. AWS collection hasn't released a version that includes the guide yet

adding argspec modifiers to docstrings

• https://github.com/ansible/ansible/pull/74873
• https://github.com/ansible/ansible/pull/74873
• and especially https://github.com/ansible/ansible/pull/74873#issuecomment-880850893
• related work happened at https://github.com/xlab-steampunk/ansible-argspec-gen#writing-module-documentation
• The content team specifically needs this for suboptions rather than for the toplevel argument spec. But making it apply to the toplevel is one of the changes abadger199 requested.

open floor

• fedora generates ansible docs so users can read them offline
• Fedora needed to patch 2.9 so it could build successfully against sphinx>=4 in rawhide: https://src.fedoraproject.org/rpms/ansible/c/f2669e12902f2fa425bcc49cb0d6a7f6bce7cfce?branch=rawhide
• the new ansible theme we use on docs.ansible.com doesn't need this, but the lexer reamains in stable.2.9 and stable-2.10
• optional fedora docs package for ansible - https://src.fedoraproject.org/rpms/ansible/blob/rawhide/f/ansible.spec#_129
• this patch could solve the problem if implemented in 2.9 and 2.10 - https://github.com/ansible/ansible/pull/74798/files (wo the regex change probly)
• :+1: if core approves, we implement the one line change so other distros can generate docs with Sphinx 4 (in stable-2.9 and stable-2.10)

Actions

• [x] @samcann to try sphinx redirects on test for docker and aws guide moves
• [x] @samccann acozine - find better wording for built-in stub page generation for collections in antsibull
• [x] @abadger1999 to look into whether required_if needs more information.
• [x] @all - read the PR https://github.com/ansible/ansible/pull/74873 and associated info shared above for argspec modifiers for docstrings and be prepared for next week's DaWGs
• [x] @- samccann to investigate if we hit this problem with 2.9 docs ourselves since 2.9 isn't using sphinx ansible theme?
• [x] @dmsimard to create PR for 2.9 and 2.10 and test before merging

Logs

Minutes: https://meetbot.fedoraproject.org/ansible-docs/2021-07-20/docs_working_group_aka_dawgs.2021-07-20-15.00.html Minutes (text): https://meetbot.fedoraproject.org/ansible-docs/2021-07-20/docs_working_group_aka_dawgs.2021-07-20-15.00.txt Log: https://meetbot.fedoraproject.org/ansible-docs/2021-07-20/docs_working_group_aka_dawgs.2021-07-20-15.00.log.html

[abadger]

There's a proposal from the ansible content team (NilashishC ) to add things like mutually_exclusive to the documentation strings: https://github.com/ansible/ansible/pull/74873 I've added a list of things I think need to happen for that to be added: https://github.com/ansible/ansible/pull/74873#issuecomment-880850893 If there's some commentary about what the docs should look like and whether I missed any steps, that would likely be good.

[samccann]

2021-07-27

Action item review

• PR to patch 2.9/2.10 to work with sphinx 4 - https://github.com/ansible/ansible/pull/75288
• required_if does not need more info
• required_if does not need descriptive test. We can construct a standard documentation sentence from what we have to give the argspec
• roles documentation from the argspec pr - https://github.com/ansible-community/antsibull/pull/272
• on https://github.com/ansible/ansible/pull/75288 - dmsimar talking with fedora to see what the status is

mutually_exclusive added to docs string

• https://github.com/ansible/ansible/pull/74873#issuecomment-880850893
• if we include this item, it needs a sanity check to make sure if the info is in the DOCUMENTATION, it matches the info in the argspec as well

Rendering collection-level docs

• https://github.com/ansible/community/issues/579#issuecomment-883649348
• today's problem - a collection contributor has no way to verify any docs changes work until after merging and AFTER uploading to galaxy. And waiting until devel docs pull in that update to docs.ansible.com/ansible/devel. And that only works for collections already in Ansible.
• the solution should allow for these contributors to generate the html, have :refs: that work, and not require deep sphinx/rst knowledge
• we could extend `antsibull-docs to create a functioning docsite (document a collection and links work to ansible docsite).
• we'd need to document how to set up and invoke this locally
• https://gist.github.com/felixfontein/6de36fff529a12b0c4ffd4aa73a82b6d (when run in an empty directory) will build a small docsite for community.docker and community.crypto
• https://gist.github.com/felixfontein/6de36fff529a12b0c4ffd4aa73a82b6d (when run in an empty directory) will build a small docsite for community.docker and community.crypto
• maybe two commands: antsibull-docs init and then the antsibull-docs collection command you already have
• the proposed antsibull init command could create an example script that runs out of the box or the user can modify as they want.
• antsibull-build should not get too involved in knowing things that other tools should do (sphinx-build options, setting up rsync, etc). But it's okay if those are in the script with sane defaults and the user can tweak them to meet their needs

openfloor

• validate-modules PR https://github.com/ansible/ansible/pull/74873 can also impact all the other users of DOCUMENTATION block, including galaxy-ng etc

Actions

• [x] @samccann and acozine - review roles docs PR one last time - https://github.com/ansible-community/antsibull/pull/272 to approve
• [x] @felixfontein to work on creating the script associated with antsibull to allow locally generated docsite for collection-level docs

Logs

Minutes: https://meetbot-raw.fedoraproject.org/ansible-docs/2021-07-27/dawgs_aka_ansible_documentation_working_group.2021-07-27-15.00.html Minutes (text): https://meetbot-raw.fedoraproject.org/ansible-docs/2021-07-27/dawgs_aka_ansible_documentation_working_group.2021-07-27-15.00.txt Log: https://meetbot-raw.fedoraproject.org/ansible-docs/2021-07-27/dawgs_aka_ansible_documentation_working_group.2021-07-27-15.00.log.html

[briantist]

I'd like to have a way to render a collection docsite (docs/docsite/rst) without cutting a release.

What is wanted

Ideally, this would include:

• the correct theme
• working links (including :ref: links) to ensure they are correct
• available at a URL so they can be browsed/inspected easily

In my ideal world, you'd be able to put up a PR to a collection's docsite, and a version of it would be generated and published as part of the PR. Not only would it be great for me as a maintainer, it would be super encouraging to anyone who wants to update docs.

Barriers

There's currently no straightforward instructions to generate all the above (even locally). I was able to use @samccann 's wonderful workaround, of copying my RST files into ansible-core and running the command to build that docsite. It doesn't quite have the structure of the collection docsite, but the theme works, and especially, the :ref: links worked, which was critical in me figuring out how to use them.

The part about serving them from somewhere is a bit tricky. readthedocs.org almost looks like it would work, but I've never used it, and it looks like the import mechanism is git based but probably not doable for PRs.

Possible (partial) implementation ideas

@felixfontein has a nice set of collection docs built into his own docsite: https://github.com/felixfontein/felix-ansible-docsite (rendered at: https://ansible.fontein.de/ ). I looked through it but there's a lot there about sphinx/etc. that I don't really understand. I'm also not certain if :ref: links to the Ansible docsite at large would work in this configuration or not; I tried to see if there were any but didn't find them, maybe have missed it.

Thinking in terms of GitHub-centric, I thought about enabling GitHub Pages, and having a GitHub Action workflow that could generate the HTML and publish it right to the local GH pages site.

I was thinking there would be a way to sort of browse each generated version, like collection.githubpages.io/pr/1234, collection.githubpages.io/branch/main whatever.

The downside of the above is that all the content needs to be committed which could only ever get committed to gh-pages or whatever branch, but still "bloats" the repo with lots of commits, moreso if it ends up being the entire Ansible docsite that needs to get rendered in order for :ref: links to work correctly.

To get around that, a separate repo for the docs only could be used; kinda messy for each collection to have its own; maybe a single repo for all (which?) collections, the ones in ansible-collections at least. A private token that allows for committing/publishing can be put into the GitHub secrets for each participating repo (I know I'm leaving out other CI for the moment).