15:03:42 <acozine> #startmeeting Docs Working Group aka DaWGs
15:03:42 <zodbot> Meeting started Tue Aug  3 15:03:42 2021 UTC.
15:03:42 <zodbot> This meeting is logged and archived in a public location.
15:03:42 <zodbot> The chair is acozine. Information about MeetBot at http://wiki.debian.org/MeetBot.
15:03:42 <zodbot> Useful Commands: #action #agreed #halp #info #idea #link #topic.
15:03:42 <zodbot> The meeting name has been set to 'docs_working_group_aka_dawgs'
15:04:06 <acozine> #topic opening chatter
15:04:09 <acozine> who's around?
15:04:13 <samccann> o/
15:04:48 <acozine> abadger1999: bcoca dericcrago dmsimard baptistemm briantist cyberpear tadeboro Xaroth zoredache
15:04:53 <acozine> you folks chatting docs today?
15:04:56 <acozine> #chair samccann
15:04:56 <zodbot> Current chairs: acozine samccann
15:04:59 <abadger1999> q qGood morning.
15:05:08 <acozine> hola abadger1999
15:05:10 * dericcrago waves
15:05:11 <acozine> #chair abadger1999
15:05:11 <zodbot> Current chairs: abadger1999 acozine samccann
15:05:14 <acozine> #chair dericcrago
15:05:14 <zodbot> Current chairs: abadger1999 acozine dericcrago samccann
15:05:18 * abadger1999 splits attention here and the discussion of how the matrix test went
15:05:33 <acozine> heh, I just can't get past the name
15:05:59 <acozine> I keep seeing scenes from the movie
15:06:24 <acozine> do I want to plug in? will I be able to run up the walls if I do?
15:06:43 <dericcrago> only one way to find out
15:06:43 <abadger1999> Hee hee
15:08:35 <acozine> official agenda: https://github.com/ansible/community/issues/579#issuecomment-887783393
15:08:54 <acozine> I have a confession - I have not looked at last week's minutes
15:09:04 <acozine> so I am flying blind, or at least with blinkers on
15:09:04 <baptistemm> me neither
15:09:12 <acozine> hey baptistemm!
15:09:15 <acozine> #chair baptistemm
15:09:15 <zodbot> Current chairs: abadger1999 acozine baptistemm dericcrago samccann
15:09:35 <abadger1999> Heh
15:09:50 <abadger1999> You just missed all your action items ;-)
15:09:59 <acozine> yep
15:10:21 <samccann> lol
15:10:22 <acozine> I spent most of my week last week cleaning up after an indoor flood
15:11:14 <acozine> caused by an air conditioning malfunction
15:11:21 <acozine> anyway . . .
15:12:10 <abadger1999> ouch
15:12:50 <baptistemm> ouch bis
15:13:01 <acozine> dmsimard: are you around?
15:13:36 <acozine> yeah, it was icky, but at least we got to it quickly, so we shouldn't have mold
15:14:27 <acozine> #topic action item re-review
15:15:03 <acozine> the PRs to backport Sphinx 4 support by updating the lexer for ansible output are both failing CI
15:15:05 <acozine> https://github.com/ansible/ansible/pull/75288
15:15:56 <acozine> the error output is in https://github.com/ansible/ansible/pull/75288#issuecomment-883566199
15:16:44 <samccann> #info pr to backport sphinx 4 support failing CI https://github.com/ansible/ansible/pull/75288#issuecomment-883566199
15:16:57 <acozine> does anyone understand the underlying issue?
15:17:28 <dmsimard> o/
15:17:35 <dmsimard> sorry multitasking
15:18:02 <dmsimard> Let's leave that one on ice for now, it may turn out to be unnecessary
15:18:42 <acozine> dmsimard: ah, that would be great
15:18:50 <acozine> dmsimard: do you want to be furniture?
15:18:58 <samccann> We had a higher level debate going - our jenkins jobs are pinned to < 4 for sphinx for older builds like 2.9/2.10.
15:19:04 <Xaroth> o7
15:19:08 <dmsimard> sure, I will fork more threads here :p
15:19:09 <samccann> so 'we' wouldn't hit this problem at all
15:19:34 <samccann> #info this PR on hold for now pending further evaluation by dmsimard
15:19:44 <acozine> hey Xaroth
15:19:48 <acozine> #chair Xaroth
15:19:48 <zodbot> Current chairs: Xaroth abadger1999 acozine baptistemm dericcrago samccann
15:19:50 <Xaroth> Afternoon
15:20:26 <dmsimard> yeah when I say unnecessary, it would be unnecessary in the particular case of fedora, I don't know if there are other downstream doc builders that have run into the issue though they could technically carry the same patch as fedora
15:20:28 <abadger1999> (My guess is that CI is using a sphinx version so old that it requires an instance rather than a class)
15:20:51 <abadger1999> I saw something about sphinx <1.8 in the CI output.
15:20:51 <acozine> yeah, from a first glance, the CI error doesn't look related to the lexer at all
15:21:00 <acozine> wow, okay, that's old
15:21:24 <acozine> so maybe we need to get that updated at least a little bit
15:21:25 <samccann> huh. how do we find out what CI is using (AND how to change that if necessary?)
15:22:31 <abadger1999> `02:17 Requirement already satisfied: sphinx<1.8 in /usr/local/lib/python3.6/dist-packages (from -c /root/ansible/test/lib/ansible_test/_data/requirements/constraints.txt (line 11)) (1.7.9)`
15:22:40 <samccann> ah I see it now. CI is using the old sphinx version we used to pin to.  So, does CI use the 'requirements.txt' files or something else to decide what version to bring in?
15:22:41 <dmsimard> <1.8 is ancient
15:22:43 <abadger1999> So CI is presently using 1.7.9
15:22:52 <acozine> #info CI is still using sphinx 1.7.9, check with testing team to update
15:23:10 <acozine> yeah, I remember that we had Jenkins pinned to 1.7.9 for a long time, though I no longer remember why
15:23:18 <samccann> #info see root/ansible/test/lib/ansible_test/_data/requirements/constraints.txt (line 11)) (1.7.9)
15:24:39 <samccann> #action docs to check with testing team on how to update sphinx 1.7.9 used in CI
15:25:45 <acozine> I'm glad the failures on those backport PRs uncovered this issue!
15:26:02 <acozine> sometimes the law of unintended consequences works in our favor
15:26:12 <samccann> yeah just took a look in devel and it's 2.1.2 or less, so we have some updating to do
15:26:46 <samccann> but I seem to recall we can't update tests in older releases. I think I tried that before and it got reverted
15:27:07 <acozine> maybe that was for Ansible <2.8
15:27:10 <samccann> something similar to we would be changing the goalposts on developers etc
15:27:10 <acozine> I hope so, anyway
15:27:35 <samccann> yeah I think we change in devel, and then ask how far back are we allowed to take it.
15:27:48 <acozine> sounds good
15:29:01 <acozine> okay, our other action items were `review the role docs PR` (samccann and myself) and `script in antsibull to allow locally generated docsite for collection-level docs` (felixfontein)
15:29:39 <acozine> role docs PR: https://github.com/ansible-community/antsibull/pull/272
15:30:20 <samccann> cyb-clock-clone sez we are 29 min into the meeting and 15 min into the current action item topic
15:30:47 <acozine> I'm still concerned about `if plugin_type == 'role'`
15:30:48 <samccann> felix has his done - https://github.com/ansible-community/antsibull/pull/297
15:31:41 <acozine> oh, awesome!
15:33:05 <abadger1999> acozine: I am too but I'm working on changing that separately... if you like the output, I'm willing to make that change in a separate PR.
15:33:30 <acozine> abadger1999: okay, that sounds good
15:33:32 <samccann> cool so we can merge the existing PR?
15:33:38 <acozine> I do think the output is good, and useful
15:33:41 <abadger1999> Cool.
15:33:56 <abadger1999> Yeah, if you all are happy with it, we can merge the role docs PR now.
15:33:59 <samccann> or do we/should we run it in jenkins first just to be sure and then merge?
15:34:11 <acozine> samccann: good idea
15:34:19 <acozine> can you kick off a run to the test site?
15:34:39 <samccann> #action samccann to stage https://github.com/ansible-community/antsibull/pull/272 on jenkins before merging
15:34:41 <samccann> uep
15:34:46 <acozine> with luck it will be done before the end of the hour and we can merge, merge, merge
15:35:24 <acozine> looks like the local-docsite script might also be ready, I can give it a quick read-through later today
15:35:52 <acozine> briantist used it with good results, so it's probably good to go
15:35:53 <samccann> can you info the pr for that?
15:36:09 <abadger1999> #info https://github.com/ansible-community/antsibull/pull/297
15:36:18 <samccann> thanks!
15:36:48 <abadger1999> Note: on that one I saw a security issue that I want to talk through with felixfontein. (doing the equivalent of mkdir -p)
15:37:12 <acozine> ah, good catch
15:37:12 <samccann> ok so we should hold off til you get that resolved
15:37:45 <samccann> #info on https://github.com/ansible-community/antsibull/pull/297 - abadger has some comments/discussions on the code before we merge
15:38:31 <abadger1999> Yeah.  It's good if you all sign off on it, and I'll sign off on it too once we resolve the security issue.
15:38:57 <samccann> cyb-clock-clone sez we are 38 min into meeting and 25 into action item topic
15:39:14 <acozine> heh
15:39:23 <acozine> well, we will save time on the next two items
15:39:25 <samccann> speaking of which you and I have at least two more action items we haven't done yet
15:39:56 <samccann> 1 - review/reword the stub page text for  collections
15:40:32 <samccann> 2 - herd the cats (aka the powers that be) to decide how to move forward on what is probably a half dozen prs related to DOCUMENTATION and ansible-docs
15:40:44 <acozine> true
15:40:48 <acozine> there's also
15:41:14 <acozine> 3 - start a list of goals for semantic markup and other changes in the pipeline
15:41:27 <acozine> and
15:41:29 <samccann> isn't that the same as 2?
15:41:40 <acozine> they're related
15:41:57 <acozine> we probably need the goals before we sit down in the Cats Meeting
15:42:24 <acozine> so we can assess how important/useful each of those half-dozen PRs might be
15:43:16 <acozine> okay, one more quick topic, then we'll do an open floor
15:43:24 <acozine> #topic moving scenario guides to collections
15:45:48 <acozine> maintainers are encouraged to open PRs to move scenario guide content out of the ansible/ansible repo
15:46:16 <acozine> https://docs.ansible.com/ansible/devel/scenario_guides/virt_guides.html
15:46:28 <acozine> https://docs.ansible.com/ansible/devel/scenario_guides/cloud_guides.html
15:46:29 <samccann> #info maintainers are encouraged to open PRs to move scenario guide content out of the ansible/ansible repo
15:46:43 <acozine> https://docs.ansible.com/ansible/devel/scenario_guides/network_guides.html
15:46:44 <samccann> should ^^ be in the next bullhorn?
15:47:05 <acozine> oh, good idea
15:47:17 <samccann> and do we specify it should be community guides only that move?
15:47:18 <briantist> hey folks, sorry, I had a conflict with this meeting today
15:47:33 <samccann> I've kind of lost the plot on what we are supposed to do with certified collection guides
15:47:34 <acozine> briantist: bummer, we've missed you
15:47:41 <acozine> samccann: I'm not sure either
15:47:51 <briantist> <3 heh thanks
15:48:20 <acozine> okay, we've got 12 minutes
15:48:21 <briantist> I know I keep spamming this but I'm just so happy with the result: https://github.com/ansible-collections/community.hashi_vault/pull/121
15:48:34 <samccann> maybe an alternate approach then is we identify which ones are community guides, and then open tickets in those repos to ask them to move them?
15:48:45 <acozine> samccann: we could try that, sure
15:49:10 <acozine> 11 minutes
15:49:11 <acozine> heh
15:49:17 <acozine> #topic open floor
15:49:29 <acozine> briantist: do you want reviews on your PR?
15:49:53 <briantist> nah it was more a demonstration of the docs generation and publishing on open PRs :)
15:49:56 <samccann> #action samccann acozine to open issues for community repos that have scenario guides we want moved
15:50:48 <acozine> briantist: ooh, nice!
15:51:10 <briantist> doesn't need to take up meeting up, just something I'm happy about and made possible by felixfontein 's PR and the discussion in the last meeting
15:51:11 <abadger1999> briantist: You should be proud :-)  It is really cool.
15:51:16 <briantist> take up meeting *time
15:51:33 <abadger1999> I wonder if that's something that should be added to the new collection templates?
15:51:56 <briantist> some it, possibly
15:52:50 <abadger1999> dmsimard: Do you know who's in charge of the new collection templates and whether briantist's "docs generation on open PRs" work would be nice to add?
15:53:32 <abadger1999> I know gundalow would know but he's on vacation for a week.
15:54:00 <dericcrago> abadger1999: there's a repo, but there's also an effort to get it included in core
15:54:20 <briantist> one part that would need more serious consideration is the use of surge.sh for the hosting, that needs an account, and is possibly pretty opinionated. A central "community account" might make the most sense for that, there are seemingly no real limits to the free account. Custom domains are free too, so a community-wide domain could be added.
15:54:30 <briantist> But yeah.. consideration needed.
15:54:33 <dericcrago> https://github.com/ansible-collections/collection_template
15:55:15 <briantist> The part that builds the docsite and uploads it as a build artifact could definitely be done, but is not quite as easy to use (have to download and unzip each build)
15:55:33 <dericcrago> and https://github.com/ansible/ansible/pull/74901/
15:55:40 <abadger1999> briantist: Cool.  I wonder if it could create a github hosted tarball that a reviewer could download and look at on their own machine or something (to avoid surge.sh)
15:56:05 <briantist> it already does that too :)
15:56:06 <abadger1999> ah, I guess that's exactly what I was wondering :-)
15:56:09 <abadger1999> Cool :-)
15:56:23 <briantist> but can't beat clicking through to a live hosted site
15:56:36 <felixfontein> o/
15:56:42 <abadger1999> dericcrago: thanks.  Does it make sense for briantist to make a PR to collection_template to add this?
15:56:45 <abadger1999> #chair felixfontein
15:56:45 <zodbot> Current chairs: Xaroth abadger1999 acozine baptistemm dericcrago felixfontein samccann
15:56:58 <acozine> oops
15:57:00 <acozine> #chair briantist
15:57:00 <zodbot> Current chairs: Xaroth abadger1999 acozine baptistemm briantist dericcrago felixfontein samccann
15:58:11 <acozine> that is very cool functionality, thanks felixfontein and briantist for creating it and doing the proof of concept
15:58:24 <briantist> the trickiest part is that changes to a `pull_request_target` workflow are hard to test, because the version in `main` is the one that will be executed on a PR. And that type is needed to have the permissions necessary to comment on the PR and/or to access secrets (only needed for publishing at the moment)
15:59:14 <dericcrago> abadger1999: I could go either way, I thought the template was loosely based on the requirements
15:59:34 <abadger1999> <nod>
15:59:55 <abadger1999> briantist: maybe bring it up at the community meeting on Wednesday?
16:00:38 <dericcrago> that sounds like a good idea or just make the PR and see what other people say :)
16:00:48 <felixfontein> +1 on that
16:00:50 <briantist> possibly, we can also stop short of template inclusion and let it bake for a bit, or otherwise have a demonstration/instructions on how to optionally incorporate it
16:01:15 <abadger1999> <nod>
16:01:31 <abadger1999> Cool :-)
16:01:56 <acozine> I find it easier to think about a topic like this when there's a PR, but we can certainly let this functionality mature for a while before we take the next step
16:02:00 <briantist> ok, I could look at adding a PR as well , whatever you all think
16:02:37 <acozine> briantist: sounds great, there's no rush
16:02:45 <acozine> any other open floor items?
16:02:56 <dericcrago> ansible fest / contributor's summit is coming up, as part of that, the community team is trying to organize a sprint / hackathon. Just wanted to get that out there if you haven't already heard. I'll have more info in the coming weeks.
16:02:57 <acozine> we're two minutes over the official meeting time
16:03:29 <acozine> #info community team is organizing a sprint/hackathon at AnsibleFest, more details to come
16:03:35 <felixfontein> \o/
16:03:50 <acozine> that will be fun
16:03:58 <felixfontein> having such a system as community.hashi_vault now has would be great for docs hackathons (or docs PRs in general)
16:04:15 <felixfontein> since you can directly see the result without having to build the site locally
16:04:20 <acozine> yes, it will make reviewing changes so much easier
16:04:21 <dericcrago> I agree
16:04:24 <acozine> and quicker
16:04:25 <felixfontein> acozine: that as well!
16:04:30 <felixfontein> (both :) )
16:04:37 <briantist> yeah, I'd love to encourage more docs changes, make small changes easier, encourage less technical users to update docs, etc.
16:05:09 <acozine> ^^^ +100
16:05:29 <acozine> oops, I'm late for my next meeting
16:05:41 <felixfontein> briantist: btw, maybe the bot's message could include direct links to the files changed? that would be a lot more complicated to implement though, but even cooler, since people don't have to figure out how to find them
16:06:01 <acozine> I'm going to close down the official DaWGs meeting, feel free to continue chatting on the channel!
16:06:11 <acozine> thanks Xaroth abadger1999 baptistemm briantist dericcrago felixfontein samccann!
16:06:20 <acozine> #endmeeting