16:02:10 <samccann> #startmeeting Documentation Working Group aka DaWGs 16:02:10 <zodbot> Meeting started Tue Jan 26 16:02:10 2021 UTC. 16:02:10 <zodbot> This meeting is logged and archived in a public location. 16:02:10 <zodbot> The chair is samccann. Information about MeetBot at http://wiki.debian.org/MeetBot. 16:02:10 <zodbot> Useful Commands: #action #agreed #halp #info #idea #link #topic. 16:02:10 <zodbot> The meeting name has been set to 'documentation_working_group_aka_dawgs' 16:02:15 <samccann> #chair acozine 16:02:15 <zodbot> Current chairs: acozine samccann 16:02:26 <samccann> #topic opening chatter 16:02:36 * samccann hands baton to acozine 16:02:53 <acozine> #chair baptistemm gwmngilfen lmodemal dmsimard felixfontein abadger1999 16:02:53 <zodbot> Current chairs: abadger1999 acozine baptistemm dmsimard felixfontein gwmngilfen lmodemal samccann 16:02:53 <felixfontein> o/ 16:02:53 * dericcrago waves 16:03:02 <acozine> #chair dericcrago 16:03:02 <zodbot> Current chairs: abadger1999 acozine baptistemm dericcrago dmsimard felixfontein gwmngilfen lmodemal samccann 16:03:08 <acozine> hey folks! good to see everyone 16:03:18 * acozine reads backscroll a bit 16:03:38 * lmodemal getting the kids some lunch. brb :) 16:03:48 <acozine> baptistemm: you okay with being furniture today? 16:04:14 <acozine> if it gets too intrusive, feel free to unchair yourself 16:05:19 <acozine> I'm multi-tasking, trying to finalize the issue about the /docs/ folder in collections 16:05:39 <acozine> samccann: you want to give an update on the core docs work? 16:06:20 <samccann> sure 16:06:31 <acozine> #topic docsite split work 16:06:31 <samccann> #topic Docsite Split Update 16:06:35 <samccann> HAHA woopsie 16:06:37 <acozine> heh 16:06:39 <acozine> go for it! 16:07:11 <samccann> ok so with abadger1999 and acozine help, I'm inching toward having a docsite split working via makefile fun and some sphinx initiatives 16:07:47 <samccann> #info WIP PR for docsite split is https://github.com/ansible/ansible/pull/73362 - still a lot to go on it 16:08:33 <samccann> The gist of it all is - it's the same set of files, but excluding scenario guides, network guides and the individual porting/maintenance pages from the relevant docs (core vs Ansible the package) 16:08:56 <samccann> #info we also have an internal build that can publish 'make coredocs' once we have all this working 16:09:04 <samccann> acozine did that part :-) 16:09:19 <samccann> (as in I couldn't explain what her magic was, but it works) 16:10:09 <samccann> So the next steps - clean up that WIP PR. The stumbling block right now is it uses a separate index page for Ansible the Package and that won't work (it's not index.html). But acozine came up with a way to use conditionals so I'm trying that next 16:11:12 <samccann> And now for the Deep Thoughts - I 'think' once this is working in devel, it all has to be backported to stable-2.10, because we need to be able to publish Ansible 3.0.0 with stable-2.10 user guides etc. BUT the question becomes - will we ALSO need to be able to publish Ansible 2.10 from stable-2.10? 16:11:24 <samccann> (as in stable-2.10 has to be able to publish THREE docsites? 16:11:40 <acozine> the core docs are still on the testing site as http://docs.testing.ansible.com/ansible-core/2.11/, but the only difference right now is the URL 16:11:42 * samccann pauses for that all to sink in 16:12:09 <felixfontein> hmm, I guess so 16:12:12 <acozine> well, the `stable-2.10` branch will need to publish both 2.10 and 3.0 16:12:29 <felixfontein> ansible-2.10, ansible-base-2.10, ansible-3 16:12:33 <acozine> does it also need to publish a separate ansible-base 2.10 docset? 16:12:58 <felixfontein> hmmm... like in "we didn't do it before, so let's not do it now"? 16:13:01 <samccann> Well to start, I think if we can keep stable-2.10 able to republish what's already out there (plus bugfixes) that's good 16:13:01 <acozine> or could we start the separate docsite with ansible-core 2.11? 16:13:22 <felixfontein> maybe starting it with ansible-core 2.11 is easier - it gives more time :) 16:13:32 <acozine> it will definitely be easier 16:13:35 <samccann> something I'm unsure of - how does antsibull decide whether to pull in the 2.10 collections list or the 3.x collections list? 16:13:45 <baptistemm> acozine: no probs 16:13:50 <acozine> will it leave any users unable to find docs they need? 16:14:30 <samccann> I'm +1 for keeping Ansible 2.10 docs as they are today.. at least for now. So the user uses the version switcher to go from 2.9 - 3. 16:14:54 <samccann> and coredocs are published separately as devel as soon as we get that working 16:14:55 <acozine> it would be nice to avoid the whole `ansible-base` to `ansible-core` thing if we can 16:15:02 <samccann> amen to that 16:17:00 <acozine> if we don't have to publish separate docs for ansible-base 2.10, then we don't have to backport samccann's changes 16:17:12 <samccann> abadger1999: how does `anstibull` decide whether to publish 2.10 collectoins vs 3.0 collections if both are being published from stable-2.10? 16:17:15 <acozine> we only need a way for the stable-2.10 branch to publish 2.10 and 3.0 16:17:32 <samccann> we do need to backport my changes, how else would we publish 3.0 from stable 2.10? 16:17:50 <abadger1999> IIRC, we tell antsibull what to do... the logic for selecting is in the ansible/ansible repo (hacking/build-ansible.py) 16:17:56 <abadger1999> But I could be misremembering 16:17:58 <samccann> ugh 16:18:19 <samccann> so something in hacking/build-ansible.py has to distinguish between 2.10 and 3.0 in the build request? 16:18:42 <abadger1999> 17 from ansible.release import __version__ as ansible_base__version__ 16:19:08 <abadger1999> Yeah, that line is from docs_build.py (under hacking) 16:20:31 <samccann> sorry can't find docs_build.py ? can you add a link? 16:20:46 <felixfontein> ./hacking/build_library/build_ansible/command_plugins/docs_build.py 16:21:04 <samccann> thanks! 16:21:08 <abadger1999> So what happens is... (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 16:21:27 <felixfontein> I guess it needs to be passed the Ansible version(s) 16:21:48 <samccann> #info 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 16:21:53 <abadger1999> (5) is actually... it finds the deps file for that version of ansible in the ansible-build-data repo and passes that to antsibull-docs. 16:22:21 <acozine> abadger1999: in step 4, how do we "get the version"? 16:22:38 <acozine> is it currently using `ansible --version`? 16:22:57 <samccann> #info (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 16:23:03 <felixfontein> 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 16:23:14 <abadger1999> acozine: python import of ansible.release.__version__ which comes from the checkout of ansible (because of doing `source hacking/env-setup.py` earlier) 16:23:15 <felixfontein> acozine: it's essentially `ansible --version`, it uses some ansible internals to get that version more directly 16:24:25 <acozine> do we need to inject the higher version numbers somehow, then? 3.0, 4.0, and so on? 16:24:25 <abadger1999> Yeah, it looks like that's going to always pull the 2.10 info. 16:24:31 <samccann> okay so in general, we need some stable-2.10 'magic coding' to have the ability to create Ansible 3 package anyway, yes? 16:26:38 <abadger1999> Yeah, looks like we're going to need to do some work there......... I think the antsibull-docs code might be able to get the version of ansible-base that it needs to satisfy the version in the ansible-build-data deps file. 16:27:29 <samccann> so... an action item for/....? (waits for volunteer from the audience) 16:28:17 <abadger1999> So one option would be to drive everything from the command line to antsibull-docs instead of this wrapper in ansible/ansible. I think that would work well in jenkins, for instance. But the wrapper in ansible/ansible is how we currently develop docs so that would mean jenkins and edveloping docs has the potential to diverge :-( 16:28:42 <abadger1999> samccann: Question: What would you like the workflow to be like? 16:28:49 <samccann> what is the difference betwen jenkins and 'developing docs' ? 16:29:16 <samccann> as in in my mind, jenkins IS developing/publishing docs.. so I'm missing a piece 16:29:35 <abadger1999> Probably starts with I checkout the branch of ansible/ansible that I want to build docs for, right? Then there has to be some way to select "Iwant coredocs" "I want ansible-2.10 docs" "I want ansible-3 docs"? 16:29:59 <samccann> yeah that part I'm working on (though 2.10 ins a new wrinkle) 16:30:51 <abadger1999> samccann: What do you see that selection looking like? 16:31:18 <samccann> well right now I was leaning toward 'make coredocs' and 'make webdocs' 16:31:27 * samccann has to figure out the correct way to format on irc 16:31:32 <abadger1999> `make webdocs ANSIBLE=2.10`;; `make webdocs ANSIBLE=3` ;; `make coredocs` ? 16:31:44 <samccann> yeah that might work 16:32:02 <abadger1999> Yeah... but there's two versions of webdocs, so we have to account for that too. 16:32:15 * acozine channels cybette . . . we're at the half-hour mark 16:32:21 <samccann> hhahaha!! 16:32:25 <abadger1999> Heh 16:32:37 <samccann> #info we may need something like `make webdocs ANSIBLE=2.10`;; `make webdocs ANSIBLE=3` ;; `make coredocs` 16:32:54 <abadger1999> If you let me know what you want to type at the command line to select between the three choices, I can design a way to make that work. 16:33:13 <abadger1999> I just don't know if the above is the way you'd want it or something else 16:33:45 <cybette> acozine ;) 16:33:46 <samccann> off the top of my head it looks like a good way to go. 16:34:17 <abadger1999> (`make ansible2docs` `make ansible3docs` `make ansiblecoredocs` ;; `make docs VER=ansible2` `make docs VER=ansible3` `make docs VER=core` ;; etc) 16:34:17 <samccann> I think I'd like to FORCE people to use ANSIBLE=xx for make webdocs so that they have to consciously decide what version they are talking about 16:34:55 <samccann> nah I like the prior one better. make coredocs is simple and I can't see that ever needing a 'version' selection like Ansible the package needs 16:34:59 <acozine> cybette: heh, I didn't mean to ping you 16:35:06 <abadger1999> `make webdocs ANSIBLE=[core|2.10|3]` 16:35:18 <abadger1999> <nod> 16:35:20 <acozine> I like that better as well 16:35:29 <samccann> i dislike that particular one because what happens when core becomes 3? I think it could be confusing 16:35:44 <acozine> hmm 16:35:57 <acozine> well, core will continue to draw its version from `ansible --version` 16:36:42 <samccann> yes but a user new to this will wonder - do a choose core or 3 as my ANSIBLE version in make webdocs? 16:36:54 <acozine> but separating the `make coredocs` and `make webdocs` commands does feel cleaner 16:37:18 <samccann> i've been leaning toward having core as clean as possible, in the inevitable future where we yank things out of ansible/ansible 16:37:22 <abadger1999> #action abadger1999 to figure out how to implement `make webdocs ANSIBLE=2.10`;; `make webdocs ANSIBLE=3` ;; `make coredocs` and report back later this week 16:37:51 <cybette> acozine: no worries! Can't offer my services right now though, having dinner... 16:37:52 <samccann> abadger1999: I may be able to figure that part out 16:37:55 <acozine> maybe the variable could be `PACKAGE`? 16:38:06 <acozine> as in `make webdocs PACKAGE=3.0`? 16:38:13 <samccann> what I can't touch is how to get ansible the package in stable-2.10 to figure out whether to build 2.10 or 3 16:39:07 <felixfontein> it gets the version to build explicitly passed 16:39:17 <samccann> ok we are 40 min in on this... should we move to another topic and abadger and I can thumbwrestle on who does what next 16:39:25 <acozine> heh 16:39:27 <acozine> sounds good 16:40:04 <abadger1999> samccann: Yeah, that's why we need to add a variable to the `make` command line 16:40:28 <samccann> ok let's brainstorm a bit later this afternoon 16:40:41 <acozine> #topic documenting use of `C(. . . )` 16:40:46 <acozine> https://github.com/ansible/ansible/pull/73312 16:41:09 <abadger1999> (Note: I have non-work stuff that will take up my afternoon... we can either work separately or brainstorm tomorrow) 16:41:15 <acozine> for history: https://github.com/ansible-collections/ansible.utils/pull/32#discussion_r560490351 16:41:33 <samccann> abadger1999: <nod> 16:41:57 <samccann> i'm +1 for using C(..) for code 16:41:59 <felixfontein> I think code fragments should always be formatted in `C(...)`, for several reasons: 1) it is a common convention, 2) it translates to <code>, i.e. semantic markup, which also helps screen readers 16:42:21 <abadger1999> +1 16:42:21 <acozine> agreed 16:42:57 <samccann> felixfontein: can you add that bit about the screen readers to the PR description. That's an important point we don't want to forget about 16:43:12 <abadger1999> I would have thought the way it was rendered would tell people it was a known standard but I guess not. 16:43:17 <felixfontein> samccann: to the PR's content, or the PR's description? 16:43:17 <acozine> this is the least controversial and the easiest to implement part of the discussion about semantic markup 16:43:27 <abadger1999> (also "C" stands for "C"ode ;-) 16:43:29 <samccann> just the description, not the actual docs change 16:44:19 <felixfontein> samccann: I updated it 16:44:21 <acozine> abadger1999: we'll always have newbies who just don't know or haven't thought of it 16:44:48 <felixfontein> true. so it's better to document it. 16:45:44 <acozine> shall we vote? 16:45:50 <acozine> any other comments/discussion? 16:46:00 <acozine> #chair 16:46:00 <zodbot> Current chairs: abadger1999 acozine baptistemm dericcrago dmsimard felixfontein gwmngilfen lmodemal samccann 16:46:26 <samccann> +1 16:46:32 <acozine> vote: +1 to merge https://github.com/ansible/ansible/pull/73312/files 16:46:34 <acozine> +1 16:46:52 <acozine> comments still welcome if you have them! 16:47:05 <felixfontein> +1 16:47:34 <dericcrago> +1 16:48:14 <acozine> that's 5 in favor, no votes against, out of 9 chairs . . . 16:48:16 <acozine> going once 16:48:23 <acozine> going twice 16:48:53 <acozine> merged 16:48:55 <acozine> thanks felixfontein 16:48:59 <felixfontein> thanks everyone :) 16:49:05 <felixfontein> I'll create a backport for stable-2.10 16:49:19 <acozine> #topic previous action items 16:50:23 <acozine> dmsimard: did you open a backport PR to add FQCN to the glossary in 2.10? 16:51:41 <acozine> I'll report on my own action item - I'm editing an issue for our discussion of publishing documentation from the `/docs/` folder in collections - the issue will be in https://github.com/ansible-community/antsibull/ 16:51:55 <felixfontein> btw, there are a couple of stable-2.10 docs backports: https://github.com/ansible/ansible/pull/73222 https://github.com/ansible/ansible/pull/73280 https://github.com/ansible/ansible/pull/73374 (ok the last one is from now ;) ) 16:52:37 <acozine> felixfontein: thanks, let me make sure we're okay to merge backports . . . I got a little hasty not long ago and had to revert a couple . . . 16:53:28 <samccann> speaking of which, I may need to revive a couple of backports once things are open again. 16:53:40 <felixfontein> acozine: I think as long as they are docs only, it should be ok 16:53:42 <samccann> one of which I think needs to be discussed with core 16:54:07 <acozine> yeah, we can have a miniature backportapalooza this afternoon 16:55:20 <acozine> #action acozine to clear the docs backports queue 16:55:39 <acozine> oops, we have five minutes left . . . 16:55:48 <acozine> I can't go over today 16:55:51 <acozine> quick open floor 16:55:59 <acozine> #topic open floor 16:56:08 <gwmngilfen> survey can wait til next week, i'm not done with it yet anyway 16:56:14 <acozine> all questions, comments, suggestions, requests for help are welcome 16:56:33 <samccann> when does Ansible 3 go to beta? 16:56:52 <acozine> gwmngilfen: sounds good, I'll make sure it's on the agenda 16:58:16 <felixfontein> I have a topic: https://github.com/ansible-community/antsibull/pull/238 16:58:22 * abadger1999 looks on ompragash 16:58:28 * abadger1999 looks on roadmap 16:59:20 <felixfontein> samccann: beginning of february 16:59:29 <acozine> so . . . next week 16:59:30 <abadger1999> 2-2 https://docs.ansible.com/ansible/devel/roadmap/COLLECTIONS_3_0.html 16:59:55 <samccann> which is next week... is it still on track for Feb 2? 17:00:10 <samccann> I ask because my goal was to have a beta docsite available 17:00:21 <samccann> may or may not be possible, but ... a goal. 17:00:22 <acozine> felixfontein: antsibull PR 238 is a big change 17:00:35 <acozine> well worth discussing in detail 17:00:41 <samccann> abadger1999: is ompragash doing the release? should I be in sync w/ him? 17:01:02 <felixfontein> acozine: it is, but necessary for Ansible 3.0.0 17:01:08 <felixfontein> because then a lot of stuff will move 17:01:15 <abadger1999> samccann: Sprry... I started replying to you and then saw a message notification from him and types his name instead of finishing the message to you 17:01:41 <acozine> felixfontein: would merging it mean no more redirects? 17:02:05 <felixfontein> acozine: redirects between stable-2.9 and the new versions are still necessary 17:02:20 <acozine> mmm, okay 17:02:21 <felixfontein> but new redirects are probably no longer necessary 17:02:21 <samccann> hah ok phew... (and sorry to our Indian peer who now has an unnecessary ping awaiting for him) 17:02:52 <abadger1999> acozine, samccann : What do you think of the output of 238? 17:03:20 <felixfontein> I can disable all the stubs for ansible.builtin for now, if that makes everyone feel better :) 17:03:37 <abadger1999> I can review the code but I saw that felix had some questions about whether the output was how we want to do it or not. 17:05:07 <acozine> I'm confused 17:05:44 <acozine> in the 'after' output here: https://ansible.fontein.de/collections/community/crypto/index.html#plugins-in-community-crypto the `_facts` module is not listed . . . 17:05:45 <felixfontein> I guess the main question is whether we want to generate stub files for ansible.builtin - I guess we don't want that, at least for the beginning. maybe later. 17:05:58 <acozine> am I looking at the right thing? 17:06:27 <felixfontein> acozine: you are. I'm not sure whether it should be listed or not; it's a deprecated redirect, so not showing it is fine IMO 17:06:28 <samccann> i'm also confused, but by a different part. so maybe a slow walkthrough would help 17:06:34 <felixfontein> on the other hand, it's not removed, so we could stlil show it 17:06:38 <samccann> but acozine - did you have a hardstop now? 17:06:43 <acozine> yeah, I need to go 17:06:52 <acozine> do you folks want to carry on with the meeting? 17:06:58 <samccann> ok let's set a 'time' where at least the three of us can discuss? 17:07:01 <abadger1999> Yeah, I think ansible.builtin might be a special case.... And we might even want to take a snapshot (as in, don't generate any stubs for things that moved in 2.10. But do generate stubs for any future moves) 17:07:01 <acozine> or shall we revive the Thursday Special for this week? 17:07:36 <samccann> well let's start with when is felixfontein available around a similar time as this in the next few days? 17:08:04 <samccann> I think 10:30 AM ET is probably the earliest that both acozine and I are around. 17:08:08 <felixfontein> if "as this" is when the meeting started, I have time :) if it's now, it's a bit suboptimal :) 17:08:33 <acozine> Thursday at the time this meeting started 17:08:36 <samccann> ok 11am ET tomorrow? 17:08:42 <acozine> um, tomorrow is Weds 17:08:45 <acozine> I'll probably be out 17:08:49 <samccann> ah ok 17:08:55 <samccann> 11am ET Thursday then? 17:09:10 <felixfontein> is that 16:00 UTC? 17:09:17 <felixfontein> (i.e. 17:00 CET) 17:09:21 <samccann> is that when this meeeting started? 17:09:23 <acozine> what time is it now? 17:09:29 <acozine> UTC I mean 17:09:54 <felixfontein> should be 17:00 UTC 17:09:57 <felixfontein> 17:09 :) 17:10:17 <acozine> yes, so 16:00 UTC on Thursday is my proposal 17:10:18 <samccann> so yes, 16:00 UTC Thursday 17:10:22 <samccann> +1 17:10:42 <felixfontein> sounds good! 17:10:51 <felixfontein> I'll be available and ready by then :) 17:10:59 <felixfontein> (I'm right now alternating between kitchen and laptop ;) ) 17:11:12 <samccann> #info we will have a supplemental meeting Thursday at 11am ET /16:00 UTC to discuss https://github.com/ansible-community/antsibull/pull/238 17:11:19 <acozine> heh, go enjoy your dinner felixfontein 17:11:20 <samccann> there. acozine shoo... I'll close this out 17:11:24 <acozine> thanks 17:11:28 <felixfontein> thanks! 17:11:31 <samccann> anyone else have anything before we end the official meeting? 17:12:25 <samccann> ok silence is golden as they say... 17:12:29 <samccann> #endmeeting