15:02:40 <acozine> #startmeeting Docs Working Group aka DaWGs
15:02:40 <zodbot> Meeting started Tue May  4 15:02:40 2021 UTC.
15:02:40 <zodbot> This meeting is logged and archived in a public location.
15:02:40 <zodbot> The chair is acozine. Information about MeetBot at http://wiki.debian.org/MeetBot.
15:02:40 <zodbot> Useful Commands: #action #agreed #halp #info #idea #link #topic.
15:02:40 <zodbot> The meeting name has been set to 'docs_working_group_aka_dawgs'
15:02:44 <acozine> #topic opening chatter
15:02:47 <acozine> who's around?
15:03:02 <samccann> \o
15:03:10 <kindlehl> \o
15:03:10 * samccann winds up the cyb-clock
15:03:37 <samccann> hi kindlehl
15:03:49 <acozine> abadger1999: andersson007_ dericcrago dmsimard gundalow aminvakil baptistemm briantist cyberpear felixfontein madonius mrproper persysted tadeboro tremble you folks talking docs today?
15:03:54 <acozine> #chair samccann kindlehl
15:03:54 <zodbot> Current chairs: acozine kindlehl samccann
15:04:02 <acozine> welcome, welcome!
15:04:07 <lmodemal> o/
15:04:12 <tadeboro> I am a bit distracted, but here (doing releases right now)
15:04:27 * cyberpear part way here
15:04:40 <acozine> tadeboro cyberpear: you want to be furniture?
15:04:48 <acozine> I think it will be a quiet day today
15:04:55 <cyberpear> no need; I'll speak up if I have comments
15:04:58 <acozine> #chair lmodemal
15:04:58 <zodbot> Current chairs: acozine kindlehl lmodemal samccann
15:05:03 <acozine> cyberpear: sounds good
15:05:32 <gundalow> Hi, back in 5
15:06:03 <acozine> gundalow: cool, wave when you're here
15:06:03 <tadeboro> I do not mind being turned into furniture, but my responses will be a bit delayed at times. Which is business as usual for me, to he honest ;)
15:06:07 <acozine> heh
15:06:09 <acozine> #chair tadeboro
15:06:09 <zodbot> Current chairs: acozine kindlehl lmodemal samccann tadeboro
15:06:19 <acozine> official agenda: https://github.com/ansible/community/issues/579#issuecomment-827803524
15:06:47 <acozine> while we're warming up . . . a few announcements
15:07:11 <acozine> new releases of Ansible 2.9 and ansible-base 2.10 went out yesterday
15:07:35 <acozine> we still need to republish the documentation, but we were able to get all the backports merged today
15:07:59 <acozine> so we are caught up with releases and preparing for the upcoming Ansible 4 release
15:08:45 <acozine> #info we are still backporting docs fixes to the 2.11 branch to prepare for Ansible 4
15:09:21 <acozine> #info 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
15:09:48 <acozine> usually we are grateful when folks open backports for typo PRs and things like that
15:10:26 <acozine> and we'll go back to that feeling once Ansible 4 is released
15:10:47 <samccann> :-)
15:11:22 <samccann> cyb-clock sez - 11 minutes into the meeting
15:11:24 <acozine> this core-release-then-package-release cadence has increased the length of our "backportapalooza" period
15:11:25 <acozine> heh
15:11:30 <acozine> keeping us honest, thanks samccann
15:11:51 <acozine> #topic breadcrumbs update
15:12:30 <acozine> the ops team gave us a few more resources for the publication job, but I have not tried it with breadcrumbs turned back on
15:12:40 <acozine> abadger1999: have you tested the build with breadcrumbs?
15:13:47 <acozine> hm, he may not be around today
15:14:07 <samccann> We can probably turn it back on in a test run and see what happens
15:14:22 <tadeboro> This is the out-of-memory problem, right?
15:14:26 <acozine> samccann: do you want to kick off a test run now, see if it finishes before the meeting is over?
15:14:37 <samccann> #action samccann to test breadcrumbs again with new jenkins job
15:14:46 <acozine> tadeboro: yeah
15:14:51 <samccann> sure I can give it a try.. just need to dust the cobwebs out of my head and remember it
15:15:04 <acozine> sphinx builds the breadcrumbs from the table of contents
15:15:12 <acozine> which it holds in memory for the duration of the build
15:15:28 <acozine> and with collections, and plugins in collections, our TOC gets really, really large
15:15:56 <tadeboro> Right, and since we have n concurrent build processes, we hold on to n copies of this already large piece of data.
15:16:06 <acozine> yes
15:16:09 <acozine> so Mr. Badger gave us a flag to turn breadcrumbs off
15:16:20 <acozine> but he could build them locally (as have others)
15:17:00 <abadger1999> I have not tested yet.  I can help test today
15:17:20 <acozine> abadger1999: hola!
15:17:24 <acozine> #chair abadger1999
15:17:24 <zodbot> Current chairs: abadger1999 acozine kindlehl lmodemal samccann tadeboro
15:17:33 <abadger1999> (sorry, I'm chauffeuring kid to school this morning)
15:18:02 <gundalow> here
15:19:01 <acozine> abadger1999: heh, we'll stop pinging you then, ping us back when you're somewhere that's not moving ;-)
15:19:04 <acozine> #chair gundalow
15:19:04 <zodbot> Current chairs: abadger1999 acozine gundalow kindlehl lmodemal samccann tadeboro
15:19:12 <acozine> #unchar abadger1999
15:19:13 <acozine> er
15:19:17 <acozine> #unchair abadger1999
15:19:17 <zodbot> Current chairs: acozine gundalow kindlehl lmodemal samccann tadeboro
15:19:23 <abadger1999> Heh :-)
15:19:36 <abadger1999> I like being uncharred too!
15:19:55 <acozine> yeah, let's keep you that way
15:20:31 <samccann> heh
15:20:58 <samccann> cyb-clock sez we are 20 min into meeting, 9 into current topic
15:20:59 <gundalow> > Right, and since we have n concurrent build processes, we hold on to n copies of this already large piece of data.
15:20:59 <gundalow> Does that mean we could reduce `n` to slow down the build, though reduce RAM usage?
15:21:44 <acozine> gundalow: we could rewrite the code that generates the breadcrumb, basically doing that ourselves instead of using the built-in Sphinx way
15:21:56 <acozine> but we'd like to avoid that if we can
15:22:29 <acozine> I suppose if we came up with an elegant, efficient solution we could open a PR back to Sphinx
15:22:47 <acozine> s/breadcrumb/breadcrumbs
15:23:10 <tadeboro> gundalow: I think we can avoid the "run one process per detected CPU" default behavior by setting sone env variable. But not an expert on the docs build setup, so I might be wrong.
15:23:41 <samccann> are there ideas or questions we should info here so we can remember and followup?
15:24:21 * acozine re-reads her comments above . . .
15:24:37 <tadeboro> I already blurted out all that came to mind. Talk first, think later ... ;)
15:25:06 <abadger1999> gundalow: yes, its possible but iirc, even two processes puts breadcrumbs over the (previous) memory threshold.  And one process is painfully slow
15:25:32 <gundalow> abadger1999: ah, OK
15:25:37 <samccann> #info can we avoid the "run one process per detected CPU" default behavior in sphinx by setting some env variable?
15:25:56 <acozine> my recollection is that the memory threshold was not super high, and the request for resources was reasonable
15:25:58 <samccann> ah okay the badger is here so I may not need to info ideas for a later date :-)
15:26:05 <abadger1999> :-)
15:26:37 <acozine> if someone can run the build on their laptop, it doesn't seem outrageous to think we could run it on the Jenkins cluster successfully
15:26:49 <abadger1999> (may be slow to respond but definitely reading the complete meeting log as i can)
15:28:23 <acozine> we'll know more once we know if another test build succeeds
15:28:42 <acozine> if it doesn't, then we probably don't have much choice
15:28:53 <acozine> because that list of plugins is not going to get any shorter as time goes on
15:29:33 <samccann> heh
15:29:49 <acozine> anything else on the topic of breadcrumbs?
15:30:11 <abadger1999> Not from me
15:30:35 * acozine nods and forges ahead
15:30:45 <gundalow> If we don' get anywhere with current ideas we should reach out to Sphinx on their Slack instance
15:30:57 <acozine> gundalow: great idea!
15:31:05 <acozine> we may not be the only ones with this problem
15:31:44 <gundalow> s/their/Write the docs/
15:32:11 <acozine> and even with smaller docsets, some flexibility in building TOCs and breadcrumbs would be nice
15:32:36 <acozine> #info if we run into blockers, we can reach out to the Sphinx maintainers on the Write the Docs Slack instance
15:32:58 <acozine> #topic /docs/ folder in collections
15:33:26 <samccann> cyb-clock not keeping up, but 33 min into the meeting
15:34:20 <acozine> we've got an open PR that allows rst content in the `/docs/docsite/rst/` folder of any collection, and builds content there to docs.ansible.com: https://github.com/ansible-community/antsibull/pull/255
15:35:34 <felixfontein> hi!
15:35:45 <acozine> yesterday I worked on a pair of branches to move the AWS Scenario Guide (https://docs.ansible.com/ansible/latest/scenario_guides/guide_aws.html) into the amazon.aws collection (https://github.com/ansible-collections/amazon.aws)
15:35:52 <felixfontein> sorry, I'm somewhat afk, but I'll try to listen in here (saw you just changed to this topic when I looked in here :D )
15:35:52 <acozine> felixfontein: hi!
15:35:57 <acozine> heh
15:36:05 <acozine> you want to be furniture felixfontein?
15:36:08 <felixfontein> sure
15:36:12 <acozine> #chair felixfontein
15:36:12 <zodbot> Current chairs: acozine felixfontein gundalow kindlehl lmodemal samccann tadeboro
15:36:38 <acozine> I got stuck on adding a link in the ansible/ansible docs that points to the collection docs
15:36:44 <felixfontein> I also have https://github.com/ansible-collections/community.docker/compare/main...felixfontein:scenario-guide for the same thing in community.docker
15:37:23 <acozine> excellent!
15:37:34 <acozine> did you do a PR to ansible/ansible that removes the content there?
15:37:45 <felixfontein> not yet...
15:38:09 <acozine> drat, so I don't have an example to copy . . . ;-)
15:38:10 <samccann> #info https://github.com/ansible-collections/community.docker/compare/main...felixfontein:scenario-guide  is an example of a scenario guide within community.docker (for POC)
15:38:12 <felixfontein> I guess I would essentially empty the existing file and add :ref:`ansible_collections.community.docker.docsite.scenario_guide` or something like that
15:38:28 <felixfontein> (or however RST references worked again ;) )
15:38:31 <acozine> heh
15:39:08 <acozine> I was trying to update the TOCs with a link across to the collection
15:39:14 <acozine> I don't think that's possible
15:40:02 <acozine> so maybe we need to phase out the TOCs and just have links on those pages?
15:40:29 <acozine> when I say "TOCs" I'm talking about https://docs.ansible.com/ansible/latest/scenario_guides/cloud_guides.html and related pages
15:40:46 <samccann> thanks was about to ask that!
15:41:16 <samccann> So I envisioned those all going away and we put redirects in place ot take folks to where the guides live within the collection index so to speak?
15:41:35 <abadger1999> I think it could be in the toc when we build them all together for docs.a.c
15:41:43 <samccann> aka we would no longer have 'scenario guides' as part of the left hand navigation at all
15:42:40 <acozine> samccann: cold turkey, eh?
15:42:50 <samccann> well with redirects ;-)
15:42:52 <acozine> heh
15:43:09 <acozine> where would we redirect that `cloud_guides.html` page to?
15:43:12 <acozine> to the collection index?
15:43:16 <samccann> We could look at analytics to see how much use those higher pages get (like cloud_guides)
15:43:23 <samccann> we could
15:43:26 <acozine> oh, I like that idea
15:43:37 <samccann> the web analytics idea?
15:43:42 <acozine> yeah
15:43:58 <acozine> if they get tons of traffic, I'll be more worried about redirecting them
15:44:14 <felixfontein> the cloud_guides.html could mention the scenario guides it knew, and mention that these are now found in every collection and point to the collection index
15:44:14 <samccann> #action samccann to find out how many hits we get on scenario toc pages like cloud_guides.html
15:44:16 <samccann> agreed
15:44:52 <acozine> felixfontein: yeah, if we remove the `toctree` construction entirely, we can do whatever we want with them
15:45:07 <acozine> and I suppose we don't need to do the entire move on the same day
15:45:08 <samccann> yeah we could also stub it for a release like felixfontein suggests, and then remove
15:45:34 <acozine> we can leave some pages in ansible/ansible or even duplicate them for a few days or weeks
15:45:40 <samccann> or orphan and stub and leave it there forever
15:45:54 <acozine> heh, true
15:46:01 <acozine> that just feels so . . . . dusty
15:46:06 <felixfontein> acozine: duplication for a short amount of time is good anyway, to avoid breakage inbetween
15:46:07 <samccann> yep
15:46:09 <acozine> but you're right, we have options
15:46:26 <acozine> felixfontein: belt AND suspenders . . .
15:46:45 <acozine> okay
15:46:52 <samccann> #info 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
15:47:22 <acozine> elroncio: welcome, you here for the Docs WG meeting?
15:47:34 <acozine> feel free to join in!
15:48:09 <acozine> okay, so are we ready to merge https://github.com/ansible-community/antsibull/pull/255?
15:48:53 <acozine> it doesn't currently have any documentation attached
15:49:10 <samccann> heh
15:49:18 <acozine> where shall we put the "how to publish user guides in your collection" documentation?
15:49:21 <samccann> yeah docs on how to use it added to antsibull docs would be great
15:49:41 <samccann> well my nickel is first step is getting it in anstibull itself (tools should be self-documented)
15:49:58 <samccann> THEN yeah, we add the details and an example to d.a.c
15:50:17 <samccann> in a new section... erm.. somewheres
15:50:22 <acozine> works for me
15:50:27 <samccann> but I'm still stuck on - are we ready to merge that pr?
15:50:52 <samccann> did you fully reproduce what felixfontein has done in the PR for examples?
15:51:02 <acozine> I have not, no
15:51:22 <felixfontein> I think the main question is how we want to include the extra files in the auto-generated collection plugin index
15:51:33 <samccann> well I guess I should ask - since you are doing all the real work, do you feel it's working (both  of you?)
15:51:40 <felixfontein> the PR uses a YAML file and allows only a very strict way of including links
15:52:10 <felixfontein> from what I remember we wanted it to be more general, but there was never a proposal how it should look like :)
15:52:33 <acozine> ah, that makes sens
15:52:36 <acozine> sense
15:53:05 <samccann> ok maybe that's an action item for the rest of us then, get more engaged on that question and come up with either a proposal or accept the current way?
15:53:07 <acozine> if I get a PR open to the amazon.aws collection repo, could I test this functionality against the PR branch?
15:53:43 <samccann> cyb-clock sez we are 53 min into the meeting, 20 min into the current topic
15:53:54 <felixfontein> acozine: yes, that should work. but maybe I should rebase the branch first, because it still includes the toctree PR which got reverted (and caused extra long build times)
15:53:54 <gundalow> (lag) Since we aren't adding anymore RSTs under https://docs.ansible.com/ansible/latest/scenario_guides/  we could the autogenerated TOC on cloud_guides.html with a manual list, which would have links to the guides still in ansible/ansible and links (intersphinx?) to the new docs in the collections
15:53:55 <acozine> there's also a question of timing - this is likely to be an Ansible 5 feature at this point, right?
15:53:56 * samccann cyb-clock has a hard stop at the top of the hr... just fyi
15:54:42 <felixfontein> acozine: we can also add it to Ansible 4 after it was released
15:54:59 <felixfontein> adding files to a collection only requires a minor release, so it can happen every 3 weeks
15:55:00 <acozine> hmm, okay
15:55:13 <felixfontein> and antsibull's release schedule is unrelated to Ansible's release schedule anyway
15:55:14 <acozine> ahh, so 4.1 could have collections scenario guides
15:55:17 <acozine> that would be awesome
15:55:39 <acozine> i was thnking more that getting content into a collection wouldn't happen in time for 4.0
15:55:46 <acozine> but 4.1 seems better anyway
15:55:55 <felixfontein> for 4.0 it has to happen until next Tuesday
15:56:01 <acozine> yeah, that's not likely
15:56:13 <felixfontein> yep, especially since the format isn't finalized yet ;)
15:56:17 <acozine> yeah
15:56:30 <acozine> felixfontein: do you have time later in the week to pair up with me on testing the PR?
15:56:58 <samccann> #info since this would just add docs files to a collection, we could implement this in the 4.x timeline
15:57:56 <acozine> oops, three minutes left
15:58:02 <samccann> heh
15:58:02 <acozine> let's do a quick open floor
15:58:08 <acozine> #topic open floor
15:58:50 <acozine> all questions, concerns, ideas, suggestions, issues or PRs for review welcome!
15:59:03 <felixfontein> acozine: probably yes
15:59:09 <acozine> felixfontein: awesome
16:00:01 <acozine> general reminders:
16:00:15 <acozine> agenda items are always welcome from anyone - just add a comment to https://github.com/ansible/community/issues/579
16:00:59 <acozine> meeting happens every Tuesday at 16:00 UTC
16:01:23 <acozine> general information on the Docs Working Group (DaWGs): https://github.com/ansible/community/wiki/Docs
16:01:46 <acozine> documentation is a great, beginner-friendly way to get involved in the Ansible community!
16:02:46 <acozine> hearing no open floor items, I think that's another DaWGs meeting done!
16:02:50 <acozine> thanks abadger1999 gundalow kindlehl lmodemal samccann tadeboro
16:03:15 <acozine> see you next week (and in channel any time before then)
16:03:18 <acozine> #endmeeting