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