15:00:42 <acozine> #startmeeting Docs Working Group aka DaWGs
15:00:42 <zodbot> Meeting started Tue Mar 30 15:00:42 2021 UTC.
15:00:42 <zodbot> This meeting is logged and archived in a public location.
15:00:42 <zodbot> The chair is acozine. Information about MeetBot at http://wiki.debian.org/MeetBot.
15:00:42 <zodbot> Useful Commands: #action #agreed #halp #info #idea #link #topic.
15:00:42 <zodbot> The meeting name has been set to 'docs_working_group_aka_dawgs'
15:00:48 <acozine> #topic opening chatter
15:00:49 <samccann> party time!!
15:00:51 <acozine> who's around?
15:00:53 <abadger1999> Ola :-)
15:00:54 <acozine> #chair samccann
15:00:54 <zodbot> Current chairs: acozine samccann
15:00:54 <tadeboro> I will be in read-only mode today. But I did find some time over the weekend to play with the role argspec in the context of documentation generation, and currently things are not there yet. Argspec does not have enough information to replace the other role documentation (examplea are the thing I missed the most). And things are mostly hardcoded in the ansible-doc itself and not reusable.
15:00:59 <acozine> #chair abadger1999
15:00:59 <zodbot> Current chairs: abadger1999 acozine samccann
15:01:09 <acozine> tadeboro: do you want to be furniture?
15:01:50 <tadeboro> I am sitting on a bench outside, so no need to furniture me.
15:02:08 <acozine> that sounds lovely!
15:02:21 <samccann> #info role argspec not quite ready for documentation generation. Still needs examples, and ansible-doc work potentially
15:02:41 <felixfontein> hi!
15:02:46 <tadeboro> Enjoying last free days before the lockdown.
15:03:05 <samccann> ooch
15:03:09 <acozine> andersson007_: bcoca dericcrago dmsimard gundalow aminvakil briantist cyberpear joedoe47 madonius Tas-sos tributarian you folks chatting docs today?
15:03:13 <acozine> #chair felixfontein
15:03:13 <zodbot> Current chairs: abadger1999 acozine felixfontein samccann
15:03:47 <acozine> tadeboro: oof, you know for sure one is coming? or you're just looking at the numbers and thinking it must be coming?
15:03:48 <dericcrago> I'm double booked so I'm half paying attention :)
15:04:05 <acozine> dericcrago: do you want to be furniture, then?
15:04:34 <tadeboro> Slovenia goes into lockdown on 2021-04-01
15:04:37 <acozine> heh, here tadeboro says "read only" and I'm asking him questions . . .I'll stop now
15:04:57 <felixfontein> :)
15:04:57 <acozine> ugh, sorry - I hope things turn around quickly!
15:05:03 <samccann> ooo I went to slovenia once! ermm. the capital and i won't even try to spell it
15:05:06 <dericcrago> maybe not
15:05:26 <acozine> dericcrago: sounds good
15:06:18 <tadeboro> I can type, but slowly ;) Smart phones are not the best thing for ircing.
15:06:48 <acozine> heh, hope
15:06:50 <acozine> er, nope
15:07:00 <acozine> apparently I can't type even on a good external keyboard ;-)
15:08:13 <acozine> if anyone else is watching this chat and wants to join, just "wave" (`o/`) or type hello and we'll make you a chair
15:08:25 <acozine> official agenda begins with https://github.com/ansible/community/issues/579#issuecomment-806037945
15:09:40 <acozine> I think sommersoft's agenda item is clear and fairly simple, maybe we can start with that
15:09:56 <acozine> #topic rules for the `docsite_pr` label on GitHub
15:10:08 <acozine> background: https://github.com/ansible/community/issues/579#issuecomment-809823241
15:11:39 <acozine> the question is: do we apply that label only when someone edits starting from docs.ansibie.com, or also when someone edits from GitHub itself?
15:12:36 <samccann> interesting question. having for only docs.ansible.com can tell us how 'popular' that feature is, especially now that it won't work on any collection level docs
15:13:04 <samccann> but how many people actually edit on github from github? I'd guess very few?  So I'd think maybe we go for whichever is easier to implement?
15:13:19 <felixfontein> I'm +1 for 'easier to implement' :)
15:13:43 <acozine> my thinking is: as a reviewer, I want that label to tell me that a PR was created by someone who may not have a lot of experience with git and they may not be able to make any changes I request unless they're github suggestions
15:13:55 <samccann> oh good point yeah
15:14:16 <samccann> some folks just can't react to a suggested edit or change because it really was a drive-by edit
15:14:29 <acozine> felixfontein: do we know which way is easier to implement?
15:14:53 <felixfontein> they can still click on 'accept' for suggestions, can't they? (or even you can if you have commit rights for ansible/ansible and they didn't uncheck the checkmark)
15:14:56 <samccann> it's possible the person directly in github is also a drive-by edit, but might be less likely.
15:15:03 <felixfontein> acozine: I don't
15:15:39 <samccann> so I think it should definitely be the label for the Edit on Github button on docs.ansible.com. If the other one is easy enough to add, I'm okay with that.
15:15:48 <acozine> +1
15:16:10 <samccann> And as a reviewer we can just assume any PR with that label may be from a novice contributor and do things like explain how to do the suggested edits acceptance
15:16:48 <samccann> #info this explains the options for the `docsite_pr` label - https://github.com/ansible/community/issues/579#issuecomment-809823241
15:16:55 <acozine> yep, and make our comments suggestions on GitHub instead of "could you add a link to Page X in this section"
15:17:47 <samccann> #info as reviewers, we should assume the PR creator may not be familiar with git etc and keep edits within 'suggested edits'
15:20:46 <samccann> so do we keep it just for the button, or tell them it has to be the button, but can be the other github thing as well if it's easier?
15:21:02 <acozine> Proposed answer: 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.
15:21:17 <samccann> +1
15:21:50 <acozine> it's really quiet today . . .
15:21:54 <samccann> that it is
15:22:20 <tadeboro> +1
15:22:21 <samccann> well not particularly controversial so I say we agree it and move on
15:22:24 <abadger1999> +1 (whatever you all think isright for this one ;-)
15:22:44 <felixfontein> +1
15:22:49 <felixfontein> sorry, im a bit side-tracked
15:22:58 <acozine> heh
15:22:59 <felixfontein> (enough that I forgot how to spell correctly...)
15:23:06 <samccann> #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.
15:23:40 <acozine> I was about to say 4 out of 5 DaWGs agree, and now it's 5 of 5 (for our non-US friends, there was a famous ad campaign years ago that said, "Four out of five dentists agree . . ."
15:23:49 <acozine> something about toothpase, or sugar-free gum, or something
15:23:51 <acozine> anyway
15:24:06 <samccann> lol
15:24:22 <samccann> ok I'll add that as a comment as well so it's not lost in meeting minutes
15:24:32 <acozine> heh
15:24:35 <samccann> (about the agreed, not the dentist
15:24:44 <samccann> ) must ... end... paren...
15:24:50 <acozine> yeah, I missed one above
15:24:54 <acozine> )
15:25:04 <felixfontein> 4 out of 5 dentists agree that you shouldn't go to the fifth
15:25:04 <acozine> #topic package `devel` docs
15:25:15 <acozine> felixfontein: heh, exactly
15:25:32 <samccann> #info - published devel with Ansible 4 collection list and it works
15:25:41 <acozine> \o/
15:25:46 <samccann> ^^ that was part of debugging yesterday's broken build.
15:25:55 <felixfontein> ah, cool!
15:26:05 <acozine> https://docs.ansible.com/ansible/devel/collections/
15:26:13 <samccann> So it's not the full proposal for sure. It just so happened that Ansible 4 collection data was available so... why not?
15:26:26 <felixfontein> I guess that list of collections also caused the out of memory for toctree ;)
15:26:40 <samccann> the what???
15:26:50 <acozine> so we discuss, and we discuss, and we discuss, and when hte moment comes for implementing, we ROCK
15:27:03 <felixfontein> the breadcrumbs PR caused the build process to die, probably because the workers died because of out-of-memory
15:27:20 <felixfontein> (since the breadcrumbs PR inserts a lot of things into the toc tree)
15:27:21 <acozine> ETOOMANYCOLLECTIONS
15:27:23 <samccann> aaah gotcha
15:27:24 <samccann> hehe
15:27:42 <samccann> So the real work is still to come for `devel`
15:28:02 <samccann> I think the proposal was to pull the most recent stable collections from galaxy.
15:28:08 <acozine> samccann: what's still on our plate for this?
15:28:25 <acozine> ah, what versions are we publishing now?
15:28:31 <samccann> some antsbull work to gather the most recent versions from galaxy
15:28:38 <abadger1999> <nod>
15:28:39 <samccann> we are publishing the Ansible 4 list
15:28:50 <samccann> that data file was there so... I hit publish
15:29:12 <acozine> ahh, so we just hit the right moment where we could get a preview snapshot, so to speak
15:29:32 <samccann> #info still to come - we need a way to pull the most recent collection versions from galaxy to publish to devel
15:29:39 <samccann> Do we have a tracking issue for that somewheres?
15:29:49 <abadger1999> joelouthan volunteered to work on that last week but I haven't seen him since the meeting.  So it's likely back on us/me to do the work
15:29:55 <acozine> good question, I don't know
15:30:04 <samccann> oh yeah now I remember
15:30:14 <acozine> huh, yeah, unless he's changed his nick, he's not in channel any more
15:30:57 <acozine> that's too bad
15:31:07 <abadger1999> If there's no ticket, I can open one now.  Which repo do you want it against?
15:31:24 <samccann> abadger1999 - i'd guess in antsibull ?
15:31:29 <acozine> I was going to ask the same question . . . the work will be done in antsibull, right?
15:31:31 <samccann> wherever the code is
15:31:37 <abadger1999> samccann: Cool, I'll ping you the link once I have it
15:31:44 <samccann> then we can add the link to the minutes. Cool
15:31:45 <acozine> +1
15:31:52 <abadger1999> probably 80% in antsibull and 20% in ansible/ansible
15:32:09 <samccann> ah gotcha
15:33:11 <acozine> the joys of distributed code
15:35:10 <felixfontein> indeed :)
15:36:58 <acozine> #topic meeting time follow-up
15:37:24 <acozine> this wasn't on the agenda, but I noticed that despite https://github.com/ansible/community/pull/602/files being merged, the UTC 1600 time is still showing up here:
15:37:42 <acozine> https://github.com/ansible/community/blob/main/meetings/ical/docs.ics
15:38:00 <acozine> someone pointed me to that, not sure right now who that was
15:39:09 <acozine> the YAML file is correct: https://github.com/ansible/community/blob/main/meetings/docs.yaml
15:39:43 <samccann> looks to be a convenient commit message above about running yaml2ical script?
15:40:22 <acozine> okay, I'll run that locally and post another PR with the results
15:40:23 <abadger1999> Yeah, running the regeneration command should generate that.
15:40:55 <abadger1999> `cd meetings; make`
15:40:58 <acozine> #action acozine to regenerate the meetings calendar for ansible/community
15:43:37 <acozine> does anyone have updates on our other ongoing topics? collection /docs/ folder, semantic markup, docs for filter/test plugins, redirects . . .
15:44:15 <acozine> unfortunately I do not for this week :-(
15:44:39 <samccann> is there  a next step for the docs folder? I lost track
15:44:40 <felixfontein> right now, no....
15:44:59 <felixfontein> samccann: I think someone needs to split the proposal up into a set of small things to decide
15:46:17 <acozine> we could expand on https://github.com/ansible-community/antsibull/issues/242
15:47:14 <acozine> I'd have to review the minutes to be sure, but my recollection is that of the two approaches outlined in that issue, we agreed to follow option A
15:47:20 <samccann> #info  collection /docs folder proposal - https://github.com/ansible-community/antsibull/issues/242
15:47:39 <acozine> so yeah, the next step would be a concrete "this is what it looks like" section
15:48:17 <acozine> a roadmap of tasks, and/or a sample collection (preferably with a transfer of docs out of the Scenario Guides section)
15:48:32 <samccann> #info 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).
15:48:33 <acozine> we've discussed some ideas lately
15:48:55 <samccann> The network team volunteered to use their new network meta collection if we need that to move the network guides to
15:48:56 <felixfontein> a WIP with sample collections is already here: https://github.com/ansible-community/antsibull/pull/255
15:48:59 <samccann> last I checked
15:49:05 <acozine> I remember we talked about whether or not we require an `index.rst` file, and if so, where that gets posted on the collection index page
15:49:19 <acozine> #topic collection /docs/ folder
15:49:20 <samccann> #WIP pr with sample collection https://github.com/ansible-community/antsibull/pull/255
15:49:26 <felixfontein> yes, we talked about that last week (?) though I don't remember what exactly we said
15:49:32 <samccann> heh
15:49:46 <felixfontein> we need some way to include content in the auto-generated index.rst file
15:49:53 <samccann> if it's more than one file it needs an index.rst
15:50:02 <felixfontein> my WIP PR does it by reading an index.yaml file and allowing very specific content to be inserted
15:50:07 <samccann> otherwise the order of the files in random
15:50:16 <felixfontein> I think abadger1999 suggested to allow more free-text inclusion
15:50:33 <abadger1999> ah right.
15:50:49 * samccann must get better at infos so we can remember stuff ;-)
15:50:54 <felixfontein> :)
15:50:58 <acozine> okay, so maybe this week's action item is to review the old minutes and update issue 242
15:51:00 <samccann> can you explain freetext inclusion again?
15:51:07 <abadger1999> we were trying to explain to each other how we think the content will fit into an index file.
15:51:12 <samccann> not much in the mintues. You'd have to read the logs
15:51:12 <acozine> I put a link to the antsibull PR there
15:51:21 <felixfontein> samccann: basically you can define some arbitrary piece of .rst which is included (somewhere) in index.rst
15:51:30 <felixfontein> you can put in there whatever you want basically
15:51:46 <felixfontein> (so you also have the freedom to wreck things)
15:52:09 <samccann> ok not sure I'm following. Is this how we inject the results in to the docs.ansible.com index.rst?
15:52:16 <felixfontein> samccann: ues
15:52:19 <felixfontein> s/ues/yes/
15:52:21 <abadger1999> So that the documentation gets linked to from a section on here: https://docs.ansible.com/ansible/3/collections/amazon/aws/index.html#plugins-in-amazon-aws
15:53:06 <samccann> ah gotcha. So 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?
15:53:39 <abadger1999> Yeah.
15:55:11 <samccann> #info 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
15:55:28 <samccann> honestly if I don't minute it I just won't remember obviously that we even had this conversation before!
15:55:42 <abadger1999> <nod> :-)
15:56:11 <acozine> samccann: maybe you and I should review some of the minutes and update the issue together later today?
15:56:19 <acozine> s/minutes/logs
15:56:20 <samccann> sounds good
15:56:36 <samccann> #action samccann acozine to review logs/minutes and update docs proposal issue accordingly
15:56:44 <acozine> nice, that will hold us more accountable
15:56:52 <acozine> okay, quick open floor
15:56:55 <acozine> #topic open floor
15:57:11 <acozine> any PRs we should be looking at? or issues?
15:57:25 <acozine> questions, comments, suggestions, ideas all welcome from anyone
15:58:26 <abadger1999> #info the breadcrumbs feature for collections was disabled due to excessive memory use
15:58:47 <samccann> cyb-clock sez 58 minutes into the meeting...
15:58:50 <acozine> heh
15:58:54 * samccann must remember cybclock!
15:59:25 <felixfontein> I'm kind of glad that the excessive memory use came from including all collections, and not just ansible.builtin
15:59:30 <acozine> I'll try to do a "minutes and cybclock" reminder during hte opening chatter
15:59:35 <acozine> heh
15:59:43 <abadger1999> If 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.
16:00:27 <felixfontein> the second solution sounds pretty ugly tbh :)
16:00:28 <acozine> is there any way to "chunk" that work more? the breadcrumbs aren't a single page like the TOC . . .
16:00:30 <abadger1999> There's also a ticket to add a command line swiotch/config option to enable breadcrumbs if someone is making their own site with less collections (or has a beefier builder)
16:00:59 <felixfontein> running sphinx with less parallelism probably also helps
16:01:01 <abadger1999> acozine: Only if we implement the breadcrumbs using our own code instead of using sphinx's toc feature.
16:01:03 <felixfontein> (though that increases runtime)
16:01:05 <abadger1999> It does.
16:01:16 <acozine> I really hope we can get the breadcrumbs up on docs.ansible.com
16:01:26 <abadger1999> I was able to run the build with CPUS=1 on a 2GB vm
16:01:33 <abadger1999> But it took forever.
16:01:40 <acozine> but I don't want to make our code unmaintainable just for that
16:02:14 <samccann> #info 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
16:02:30 <acozine> all right, plenty of work on our plates . . .
16:02:45 <felixfontein> how much parallelism is the currnt docs build using (with how much RAM total available)?
16:03:40 <abadger1999> Let me see if I can find those pieces of info in the jenkins logs
16:03:52 <abadger1999> CPUS=4
16:04:17 * acozine steps away briefly
16:04:35 <abadger1999> jenkins config for that worker seems to say 2GB minimum and 4GB maximum
16:06:02 <abadger1999> #info ticket to add a config option to enable collection breadcrumbs: https://github.com/ansible-community/antsibull/issues/267
16:06:27 <samccann> so for jenkins  it's less cpus (and take forever) or ask for more ram?
16:06:42 <abadger1999> samccann: With the current code, yes.
16:06:59 <samccann> yeah would prefer to keep sphinx breadcrumbs if possible
16:07:36 <samccann> does anything run the jenkins jobs besides 'publish the docs?"  As in what's the impact of having a really slow docs build?
16:07:44 <abadger1999> I didn't scope out precisely how much RAM would be needed and as the amount of modules and plugins increases, the amount of RAM will increase too
16:07:52 <samccann> true
16:08:58 <samccann> is there something we know of in the sphinx breadcrumbs that could be fixed in a PR there? as in make it better/faster vs rolling our own?
16:09:32 <abadger1999> I don't think there's anything running the ansible package docs build.  I know the ansible-core docs build is run by the ansible-core release job
16:09:47 <abadger1999> Nothing that we know of.
16:10:40 <samccann> ok. let's think Deep Thoughts on this one. Seems like an ever-growing list of modules will mean we'll be chasing ram increases over time.
16:10:41 <abadger1999> There's probably ways to optimize for memory usage but I haven't looked at all
16:11:37 <samccann> Is there a way to turn one of the jenkins build (say the nightly one) to use just 1 CPU or whatever is needed to get the build running with the most recent anstibull?
16:12:14 <abadger1999> samccann: we can pass CPUs=1 in the jenkins buld script without reconfiguring the jenkins workers if we want to
16:12:46 <samccann> #info we could pass CPUs=1 in the jenkins buld script without reconfiguring the jenkins workers, maybe on the nightly build?
16:12:57 <samccann> ok won't drag this meeting out any longer, but it's something to think about
16:13:08 <samccann> Anyone have anything else to discuss before we end?
16:13:10 <abadger1999> samccann: Note that the most recent antsibull has breadcrumbs disabled.  We'll need to also add the switch to re-enable it if we want to be able to tune it on a per-invocation basis.
16:13:25 <samccann> ok thanks
16:13:48 <samccann> #info if we test this, we need to use antsibull==0.29.0 as most recent has breadcrumbs disabled
16:14:27 * acozine is back
16:14:47 <samccann> are we ready to wrap this up?
16:15:02 <samccann> any other topics, issues, PRs to discuss?
16:16:19 <acozine> doesn't sound like it . . .
16:16:23 <samccann> ok!
16:16:26 <samccann> #endmeeting