15:01:29 <acozine> #startmeeting Documentation Working Group aka DaWGs
15:01:30 <zodbot> Meeting started Tue Aug 10 15:01:29 2021 UTC.
15:01:30 <zodbot> This meeting is logged and archived in a public location.
15:01:30 <zodbot> The chair is acozine. Information about MeetBot at http://wiki.debian.org/MeetBot.
15:01:30 <zodbot> Useful Commands: #action #agreed #halp #info #idea #link #topic.
15:01:30 <zodbot> The meeting name has been set to 'documentation_working_group_aka_dawgs'
15:01:31 <briantist> o/
15:01:34 <acozine> #topic opening chatter
15:01:37 <acozine> who's around?
15:01:39 <acozine> #chair briantist
15:01:39 <zodbot> Current chairs: acozine briantist
15:01:45 <acozine> hey briantist, how's it going?
15:01:52 <briantist> not bad, yourself?
15:01:53 <abadger1999> Bom dia
15:01:59 <acozine> #chair abadger1999
15:01:59 <zodbot> Current chairs: abadger1999 acozine briantist
15:02:12 <acozine> decent, we're finally getting some much-needed rain and coolth
15:02:22 <samccann> o/
15:02:27 <acozine> #chair samccann
15:02:27 <zodbot> Current chairs: abadger1999 acozine briantist samccann
15:02:37 <abadger1999> Yay!
15:02:42 <felixfontein> o/
15:02:50 <acozine> #chair felixfontein
15:02:50 <zodbot> Current chairs: abadger1999 acozine briantist felixfontein samccann
15:03:03 <tadeboro> o/
15:03:03 <acozine> official agenda begins with: https://github.com/ansible/community/issues/579#issuecomment-892094589
15:03:09 <acozine> #chair tadeboro
15:03:09 <zodbot> Current chairs: abadger1999 acozine briantist felixfontein samccann tadeboro
15:04:03 <acozine> dericcrago: dmsimard cyberpear Xaroth you folks chatting docs today?
15:04:43 <dmsimard> busy with dad ops, will respond to pings with latency
15:05:07 <acozine> for anyone watching this chat and thinking, "Hm, acozine didn't mention my name, what does that mean?" . . . it means you either haven't participated before, so I don't want to bother you, or I've forgotten you participated before . . . and you are very welcome to participate now!!!
15:05:13 <acozine> dmsimard: understood, thanks
15:05:39 <acozine> for anyone who wants to join the fun, just wave, like this:
15:05:44 <acozine> o/
15:05:58 <acozine> and we'll make you a chair of the meeting
15:06:24 <acozine> wave at any time
15:06:32 <acozine> meanwhile we'll go on with the agenda
15:06:58 <acozine> #topic action item review
15:07:05 <acozine> yikes, this might be painful
15:07:12 <samccann> heh
15:07:57 <samccann> must be the non-action action item review time
15:08:08 <acozine> let's see, the pygments_lexer fix for the 2.9 docs . . .
15:08:48 <acozine> this was prompted by fedora, they wanted a way to build the 2.9 documentation with Sphinx 4, which is the default in the new fedora release
15:09:11 <acozine> I hear they found a workaround and don't need this change any more
15:09:19 <acozine> which is good, because it never passed CI . . .
15:09:44 <tadeboro> Yeah, that fix was too optimistic ;)
15:10:07 <acozine> samccann: you are correct
15:10:11 <acozine> tadeboro: you are also correct
15:10:31 <acozine> let's see, how can we info that . . .
15:10:52 <tadeboro> I would assume that fedora can patch the relevant parts (I used to do such things for Gentoo back in the days).
15:11:00 <acozine> #info fedora found a workaround for the 2.9 documentation, we will continue to build those docs with Sphinx <4
15:12:06 <acozine> the sphinx-init antsibull-docs enhancement (https://github.com/ansible-community/antsibull/pull/297) has been merged
15:12:24 <acozine> thanks felixfontein briantist abadger1999 and all the others who worked on that PR
15:13:08 <briantist> it's great stuff! (I didn't actually work on it but did put it to great use, so thanks everyone!)
15:13:09 <abadger1999> I'll make a new antsibull release by the end of the week so it's just a pip install away (if I've forgotten, poke me with a sharp stick anytime between Friday and next docs meeting ;-)
15:13:12 <acozine> #info merged https://github.com/ansible-community/antsibull/pull/272 for sphinx-init antsibull-docs
15:13:33 <acozine> oops, wrong PR
15:13:35 <acozine> #undo
15:13:35 <zodbot> Removing item from minutes: INFO by acozine at 15:13:12 : merged https://github.com/ansible-community/antsibull/pull/272 for sphinx-init antsibull-docs
15:13:49 <acozine> #info merged https://github.com/ansible-community/antsibull/pull/272 for role documentation
15:14:06 <acozine> #info merged https://github.com/ansible-community/antsibull/pull/297 for sphinx-init antsibull-docs
15:15:04 <briantist> I updated my PR docs build workflow shortly after the last meeting to build both the target branch (main) and the PR's docs, and then compare hashes, so that it doesn't publish the docs or comment on the PR unless the docs were actually changed. It does add a little complexity but it's nice.
15:15:13 <acozine> #action carryover item: acozine samccann to check with testing team about updating Sphinx in CI (currently using 1.7.9)
15:15:34 <briantist> But I haven't yet updated it to use the Ansible theme, looking forward to that but busy some other things at the moment.
15:15:37 <acozine> briantist: that sounds like an efficient way to approach things
15:16:17 <abadger1999> Nice :-)
15:16:48 <acozine> #action carryover item: acozine samccann to open issues for community scenario guides to be moved to collections
15:16:58 <samccann> ;-)
15:17:03 <acozine> anything else I forgot about from action items?
15:18:42 <abadger1999> #action abadger1999 to make a new antsibull release this week with role docs and antsibull-docs init features.
15:18:52 <acozine> \o/
15:18:57 <samccann> woot!
15:19:15 <samccann> as for old action items - we still need a process for getting folks to agree on ansible-doc etc related changes
15:19:24 <abadger1999> Update on that.
15:19:47 <acozine> yeah, I think that's a whole topic on its own
15:19:48 <abadger1999> We now have a way to reach the  internal stakeholders together to discuss that
15:19:48 <acozine> #topic goals for ansible-doc output, semantic markup, and other future changes to the documentation ecosystem
15:20:17 <abadger1999> #info internal mailing list setup to get internal stakeholders talkng about changes to docs.
15:20:31 <acozine> that will be a huge help
15:21:02 <acozine> can we come up with a list of community goals?
15:21:03 <abadger1999> One of the primary discussions we're going to have on that list is setting up a public process so that we still have hte ear of the internal folks but external folks aren't excluded
15:21:42 <acozine> one of our goals is "provide a way to document every element in a collection"
15:21:50 <acozine> we've made huge strides on this
15:22:00 <acozine> collection-level guides, role documentation
15:22:12 <abadger1999> (for instance, tadeboro's critique of role documentation; felixfontein's note that tests were disabled on the attributes PR.
15:22:22 <samccann> i feel like a goal is continuous improvement with community ideas etc
15:22:43 <samccann> like the semantic markup etc
15:22:52 <samccann> and another goal is 'don't break things' :-)
15:23:05 <acozine> heh
15:23:35 <samccann> semi related - I feel like we are set up for a divergence in information.
15:23:51 <acozine> samccann: say more about that
15:23:54 <samccann> So for example, if collection /docs folder has md - it shows up in galaxy-ng but not docs.ansible.com.
15:24:12 <samccann> and with the roles argspec - it shows up on docs.ansible.com, but not galaxy-ng, etc
15:24:43 <acozine> true
15:24:47 <samccann> so collection maintainers are facing an either/or here - either they have their docs on docs.ansible.com (if they are in Ansible) or they have it on the future of galaxy-ng, but not on both for some of these things
15:25:07 <acozine> so, is one of our goals to work toward the same documentation everywhere?
15:25:44 <samccann> dunno. I think it's worth asking what folks here think. Maybe nobody in the community is interested in the .md option in galaxy-ng so it won't matter?
15:25:56 <acozine> tadeboro: briantist felixfontein what do you think about possible divergence between docs.a.c and Galaxy?
15:27:08 <briantist> I think a divergence is bad. The same info should be available on both. For collections in Ansible, I would almost rather Galaxy link to docs.a.c, but that might not be the best UX
15:27:08 <acozine> is it a problem?
15:27:11 <tadeboro> What samccann said about divergence is what I find the most troublesome right now. Because I either have to have at least two sets of documents with roughly the same info (one for AH, one for docs.ansible.com).
15:28:11 <tadeboro> And as the end result, we are currently self-hosting all of the docs ourselves and link to them in other places (for example, on AH).
15:28:14 <acozine> I think Galaxy can link to docs.a.c . . . but maybe that's only "old" Galaxy, not galaxy_ng
15:28:32 <briantist> I don't really use much from Galaxy except the collections in Ansible so I'm not the best person to have a POV on galaxy-side docs, but having to maintain two sets is troublesome.
15:28:39 <samccann> anyone can set it up in both so the 'docsite' link goes to their collection info on docs.ansible.com
15:29:03 <tadeboro> For certified collections, things are even worse since some of the docs only end on access.redhat.com
15:29:20 <briantist> 😵
15:29:28 <samccann> seems like where it really becomes a problem is  yeah, the AH/certified stuff who also want to maintain a community presence.
15:29:56 <acozine> tadeboro: I had no idea anything from AH ended up on access.redhat.com . . .
15:30:17 <samccann> yeah that's new to me as well. can you elaborate?
15:30:30 <acozine> I know we are creating downstream guides that are / will be published there, but I didn't know anything from collections went there
15:31:18 <acozine> tadeboro: do you have an example?
15:31:33 <tadeboro> acozine: Things that end up on access.redhat.com are not part of AH, you are right. Those are actually a third kind of docs I need to help maintain for some certified collections.
15:32:55 <acozine> oh dear, that's unfortunate . . . how are those "third kind" docs written/hosted/published?
15:33:02 <tadeboro> servicenow.itsm docs are partly available on AH and scenario guides will live on access.redhat.com
15:33:25 <samccann> ah
15:33:38 <tadeboro> And there is no "community" docs for this collection apart from the rst files in the repo since that collection is not part of the ansible PyPI package.
15:34:07 <samccann> so a collection maintainer might need docs in rst (for docs.ansible.com), md (for AH) and asciidoc (for access.redhat.com)
15:34:33 <tadeboro> There is not much we can do about the access.r.c, but I hope we can unify the rest of the stuff in some way.
15:35:24 <samccann> #info collection maintainers have to choose between docs.ansible.com (rst) and AH (md) or author in both if they want a presence in community and product.
15:37:04 <acozine> I could see a future in which the collections index page for docs.a.c is a list of links to Galaxy and docs live in Galaxy
15:37:27 <acozine> or one where collections in Galaxy link to docs.a.c for docs
15:37:40 <samccann> only if galaxy increases its support w/ md etc
15:37:54 <samccann> right now it's kind of limited as I understand it (tho my info is a year old)
15:37:55 <tadeboro> For me personally, beig able to add examples to reference docs for roles, would solve quite a few issues. Those docs can then be displayed by galaxy_ng just fine probably.
15:38:23 <samccann> are you talking about getting EXAMPLES in the role argspec?
15:38:38 <tadeboro> That would work, yes.
15:38:46 <samccann> and then getting galaxy-ng to display the roles docs?
15:39:16 <tadeboro> Yep. IIRC, AH already displays info from that argspec in some way.
15:39:28 <tadeboro> But it has been a while since I logged into AH for the last time.
15:40:00 <acozine> I didn't know AH supported role docs at all
15:40:09 * acozine digs for AH login
15:40:52 <samccann> heh
15:42:19 <samccann> ok I checked sensu_go, which is the only collection I know of with roles docs based on the roles argspec and they dont have roles docs there. They point off to their own docsite for different docs than what would come from the argspec
15:42:27 <samccann> oh shoot
15:42:41 <samccann> cyb-clock-clone wakes up to say we are 42 minutes into the meeting
15:42:59 <samccann> ...and 42 min into action item reviews
15:43:17 <acozine> well, only in the sense that we have no real "new business"
15:43:18 <tadeboro> Ah, yes, AH display role's README file.
15:44:08 <acozine> yeah, I see that
15:44:25 <acozine> okay, since we're getting close to the end of the hour
15:45:11 <samccann> #info afaik AH does not use the roles argspec yet for role docs
15:47:54 <acozine> so our goal is to have as much of the documentation standardized across community and product docs as possible?
15:48:26 <tadeboro> That would make me very happy ;)
15:48:28 <acozine> in other words, to use one source for documentation with multiple display options?
15:48:53 <samccann> kind of like ansible-docs does (which I think displays roles docs now?)
15:49:28 <tadeboro> Yes, ansible-doc can print reference docs for roles if they have argspecs.
15:49:48 <acozine> does the output of `ansible-doc` gets displayed anywhere for product docs? AH? access.rh.com?
15:49:54 <acozine> I don't think it does right now
15:50:02 <acozine> s/gets/get
15:50:20 <tadeboro> As far as I can tell right now, no.
15:51:03 <samccann> `ansible-doc` is the source for the plugin docs today on AH.
15:51:21 <acozine> ah, okay
15:51:34 <samccann> So one 'might' assume AH could eventually use that for roles docs as well. But that's just a guess and doesn't help with scenario guides
15:53:21 <acozine> okay, so best case scenario would be module and role reference docs get generated from the docstrings to three places: command line, community docs (for collections in Ansible), and product docs (for certified collections)
15:54:29 <acozine> the collection-level docs (scenario guides) are a separate conversation
15:55:11 <samccann> yep
15:55:14 <samccann> 5 min left
15:55:15 <acozine> okay, thanks for talking through this, folks!
15:55:21 <acozine> yeah, let's do a quick open floor
15:55:30 <acozine> #topic open floor
15:56:00 <acozine> anyone have a PR that needs attention? or an issue the DaWGs can help with?
15:56:14 <acozine> a suggestion, question, idea, or complaint?
15:56:17 <acozine> now is the time!
15:58:29 <acozine> going once
15:58:35 <acozine> going twice
15:58:36 <samccann> ;-)
15:58:42 <acozine> wow, are we going to finish EARLY?
15:58:51 <acozine> I didn't know that was possible!
15:58:52 <samccann> SOLD to the little lady in the pink calico dress!
15:58:56 <acozine> heh
15:59:17 <acozine> okay, thanks abadger1999 briantist dmsimard felixfontein samccann tadeboro
15:59:33 <acozine> add agenda items at any time to https://github.com/ansible/community/issues/579
15:59:45 <acozine> chat in the channel welcome at all times
15:59:49 <acozine> #endmeeting