16:00:37 <acozine> #startmeeting Docs Working Group aka DaWGs
16:00:37 <zodbot> Meeting started Tue Mar 23 16:00:37 2021 UTC.
16:00:37 <zodbot> This meeting is logged and archived in a public location.
16:00:37 <zodbot> The chair is acozine. Information about MeetBot at http://wiki.debian.org/MeetBot.
16:00:37 <zodbot> Useful Commands: #action #agreed #halp #info #idea #link #topic.
16:00:37 <zodbot> The meeting name has been set to 'docs_working_group_aka_dawgs'
16:00:40 <acozine> #topic opening chatter
16:00:42 <abadger1999> Thanks :-)
16:00:43 <acozine> who's around?
16:01:00 <felixfontein> hi!
16:01:02 * samccann waves
16:01:03 <tadeboro> o/
16:01:08 <joelouthan> howdy
16:01:12 <acozine> #chair felixfontein samccann tadeboro joelouthan
16:01:12 <zodbot> Current chairs: acozine felixfontein joelouthan samccann tadeboro
16:01:18 * abadger1999 half here
16:01:27 <acozine> welcome joelouthan I think this is your first DaWGs meeting
16:01:54 <acozine> the way we usually do this is, anybody who chats gets "turned into furniture" (becomes a "chair" of the meeting)
16:01:58 <acozine> but it's optional
16:02:08 <acozine> so feel free to unchair yourself if that's more comfortable
16:02:15 <acozine> abadger1999: I won't make you furniture
16:02:20 <acozine> unless you want me to ;-)
16:02:27 <joelouthan> I have been in one before but I was just stalking
16:02:43 <acozine> awesome, I'm glad you're taking that next step!
16:03:15 <acozine> anybody else around?
16:03:58 <acozine> andersson007_: bcoca dericcrago dmsimard gundalow aminvakil briantist cyberpear Tas-sos tributarian you folks talking docs today?
16:04:07 * dericcrago waves
16:04:14 <acozine> #chair dericcrago
16:04:14 <zodbot> Current chairs: acozine dericcrago felixfontein joelouthan samccann tadeboro
16:04:22 * cyberpear half here
16:04:23 <acozine> official agenda begins with https://github.com/ansible/community/issues/579#issuecomment-800606449
16:04:33 <acozine> cyberpear: you want to be furniture?
16:04:48 <cyberpear> no need to be furniture today :P
16:04:58 <acozine> sounds good
16:05:06 <acozine> #topic meeting time for summer
16:05:11 <acozine> we forgot this one last week
16:05:16 <acozine> here's the background:
16:05:31 <acozine> our meetings are scheduled in UTC
16:06:06 <acozine> but last fall when the time changed, we agreed to change the UTC time to be more humane for regulars on the US West Coast
16:06:48 <acozine> now that the time is changing again, we probably want to shift back a bit so folks in Europe can do other things in the evening
16:07:22 <acozine> So what times work for folks?
16:07:26 <felixfontein> right, in two weeks it would be 18:00 for me :)
16:07:55 <felixfontein> how about moving it to one hour earlier? I think that's what we had before
16:07:57 <samccann> is that a good time? as in if we wait 2 weeks, does this resolve itself?
16:08:07 <tadeboro> I am fine with either keeping the time the same or moving it a bit. It does not make enough difference for me to care much.
16:08:08 * samccann timezone challenged
16:08:44 * gundalow waves, half here
16:08:48 <acozine> abadger1999: as our stalwart west-coaster, would an hour earlier work for you?
16:09:23 <acozine> this time works for me; an hour earlier works for me also
16:09:32 <samccann> same here either works
16:09:33 <tadeboro> I thing certain badger preapproved things in the issue comment.
16:09:34 <acozine> gundalow: do you want to either be furniture, or weigh in on scheduling, or both?
16:09:42 * acozine looks at the agenda
16:09:58 <abadger1999> Yes :-)
16:10:05 <abadger1999> an hour earlier is fine for me
16:10:06 <acozine> ah, yes, thanks abadger1999 sorry for the pings
16:10:26 <gundalow> acozine: I'll stand if that's OK. Feel free to ping me if there is something specific
16:10:36 <acozine> yep, no worries
16:10:42 <gundalow> I'm happy for the meeting to stay or move
16:10:53 <acozine> okay, so far one hour earlier is okay for everyone who has spoken up
16:11:11 <samccann> do we mark it as agreed?
16:11:17 <acozine> is there anyone here who would find it harder to attend this meeting one hour earlier?
16:12:28 <acozine> hearing no big objections, I'd say one hour earlier is agreed
16:12:51 <samccann> #agreed we will move this meeting one hour earlier starting next week
16:13:15 <samccann> do you remember how to update the meeting calendar acozine?
16:13:15 <acozine> this means folks whose time has not yet changed will have a bit of back-and-forth
16:13:16 <felixfontein> \o/
16:13:28 <felixfontein> true :)
16:13:38 <acozine> that seems fair, since those of us whose time has already changed have had a bit of back-and-forth already
16:13:47 <baptistemm> hello
16:13:48 <acozine> share the pain a bit . . .
16:13:53 <acozine> baptistemm: welcome!
16:13:58 <acozine> #chair baptistemm
16:13:58 <zodbot> Current chairs: acozine baptistemm dericcrago felixfontein joelouthan samccann tadeboro
16:14:04 <felixfontein> though actually ... time will change in Europe on March 28th, so before the next meeting ;)
16:14:14 <acozine> oh, that makes it easy, then
16:14:22 <felixfontein> indeed!
16:14:34 <acozine> #action acozine to change the UTC time schedule for the DaWGs meeting
16:15:54 <acozine> #topic update on `devel` docs
16:16:02 <acozine> this is one of our long-running topics
16:16:28 <acozine> do we have any next steps we can take this week?
16:16:55 <felixfontein> abadger1999 wrote something on that
16:17:04 <felixfontein> (haven't read it yet though)
16:17:14 <samccann> this is how to get an Ansible the package devel docs right?
16:17:27 <acozine> yes and yes
16:17:41 <acozine> here's the doc mentioned above: https://hackmd.io/E5a0dw0tTDCteQVVk4VvJw?both#Development-of-ansible-core-and-latest-of-collections
16:18:16 <felixfontein> it sounds like what we discussed earlier
16:18:29 <samccann> #info options for a Devel version of ansible-core and the latest collection versions https://hackmd.io/E5a0dw0tTDCteQVVk4VvJw?both#Development-of-ansible-core-and-latest-of-collections
16:18:34 <acozine> yeah, we've been a few rounds on this question before
16:19:02 <felixfontein> yep
16:19:12 <acozine> one of these meetings we will finally make some progress on it
16:19:21 <samccann> is next step to get working code?
16:19:42 <samccann> i can't recall any debate on what we should publish
16:20:15 <felixfontein> samccann: I think it is
16:20:59 <acozine> ah, it's coming back to me now
16:21:04 <felixfontein> I think we discussed whether we wanted to have the latest ansible-core release or devel branch (and decided for devel branch), and we discussed whether we want git versions, latest prereleases, or latest relesaes of collections (and decided for latest releases)
16:21:05 <samccann> heh
16:21:15 <acozine> we decided that we would only include released versions of collections
16:21:16 <samccann> yep
16:21:41 <acozine> yeah, so I think our next step would be implementation
16:21:58 <acozine> I'll update the hackmd file to reflect that
16:22:31 <samccann> #info next step is to implement this idea
16:23:38 * abadger1999 back to full attention for this meeting :-)
16:24:29 <abadger1999> Yeah, I think the implementation steps in that particular section will do what we want.
16:24:37 <acozine> #chair abadger1999
16:24:37 <zodbot> Current chairs: abadger1999 acozine baptistemm dericcrago felixfontein joelouthan samccann tadeboro
16:25:45 <acozine> yeah, the only downside of the way we've agreed to go is that the docs for ansible-core devel will get out ahead of the next Ansible package release in the gap between when a stable branch is cut and when the next Ansible package gets released
16:26:03 <acozine> but that's not terrible, and we get a lot of benefits from this approach
16:26:33 <acozine> any discussion/ideas/suggestions/questions about implementation?
16:26:59 <abadger1999> I think the code for all of that has stubs to drop in the functionality we need.  So no major restructuring would be needed.  There is probably 50-50 new code and gluing existing code together to be done.
16:27:12 <acozine> that's excellent
16:27:44 <felixfontein> it's basically that someone has to volunteer to do it ;)
16:28:41 <acozine> unless someone is itching to volunteer right now, that's all the discussion we can have
16:28:54 * acozine waits a beat before changing topics, just in case . . .
16:28:59 <joelouthan> ...
16:29:11 <joelouthan> who can I speak to about volunteering and all that is involved
16:29:17 <joelouthan> I think that is something I can do
16:29:23 <abadger1999> joelouthan: You can talk to me :-)
16:29:24 <acozine> joelouthan: oh, awesome
16:29:40 <acozine> thanks for volunteering
16:29:55 <abadger1999> This is the main part that will need implementing: "Enhance antsibull-docs to create documentation based on the ansible-build-data/NEXT/ansible.in file"
16:30:07 <abadger1999> I can show you around the code after the meeting if you want.
16:30:18 <joelouthan> yes please and thank you
16:30:26 <abadger1999> Thank you! ;-)
16:30:45 <acozine> #topic breadcrumbs
16:31:22 <acozine> just a quick thanks to felixfontein for creating the PR and to everyone who chimed in on https://github.com/ansible-community/antsibull/pull/240
16:31:23 <github-linkbot> https://github.com/ansible-community/antsibull/pull/240 | closed, created 2021-01-17T13:56:50Z by felixfontein: Add breadcrumbs to collection index, plugin indexes etc., and add namespace indexes [bug,enhancement]
16:31:44 <acozine> I don't think we've published that to `latest` yet
16:31:48 <acozine> but it will be up soon!
16:31:53 <felixfontein> acozine: it just got merged :)
16:32:08 <acozine> \0/
16:32:20 <acozine> anyway, thanks for the forward momentum
16:32:21 <samccann> woot!
16:32:32 <felixfontein> I'm looking forward to see that in action!
16:32:36 <acozine> me too
16:32:56 <acozine> I'll post here when we get it onto test, just for a last set of eyes before it goes into production
16:33:09 <acozine> #topic collection /docs/ folder
16:33:40 <felixfontein> acozine: thanks!
16:34:14 <felixfontein> any news on that from the AH / galaxy team?
16:35:34 <acozine> the best I can say is that this will be a multi-phase effort
16:35:59 <acozine> and we may end up with multiple options for adding documentation to collections
16:36:16 <acozine> in markdown, in rst, maybe even more optons
16:36:22 <acozine> s/optons/options
16:37:15 <acozine> making docs visible in the community galaxy UI is not at the top of the priority list
16:37:33 <felixfontein> i.e. same as community galaxy itself :)
16:37:43 <acozine> yep
16:38:42 <acozine> we can migrate the existing rst files into /docs/docsite/rst/, require an `index.rst` file there, and publish them to docs.ansible.com
16:39:08 <acozine> knowing, however, that the approach may become obsolete over time
16:39:16 <felixfontein> in which sense obsolete?
16:40:01 <acozine> in the sense that if Galaxy does eventually show docs, it will likely be in markdown
16:40:22 <acozine> so collection owners may then need to convert rst docs
16:40:36 <acozine> and/or the rst docs may become hopelessly out of date
16:41:03 <tadeboro> Which sound a sure way of making sure galaxy has no docs if the author already went through the troble of writing them in rST.
16:41:41 <acozine> tadeboro: true, but galaxy has no docs now, and we don't know how long that will continue
16:42:07 <acozine> it's not a great situation
16:42:07 * tadeboro is a bit annoyed with docs right now because he is forced to write them in md so that they show on AH.
16:42:38 <samccann> sadly out of our sphere of influence
16:42:45 <acozine> tadeboro: sorry, I wish we had more say in that
16:43:25 <abadger1999> From what was said at the contrib summit, my guess is that there won't be docs on galaxy until the code base moves to galaxy-ng which will have to wait until galaxy-ng grows roles support.
16:43:26 <felixfontein> ok, so for now, how about ignoring galaxy since it is totally unclear if they will support docs in a month, half a year, one year, two years, ...? :)
16:43:41 <tadeboro> I did not expect solutions. I am just explaining why I may come across as in a bad mood and why you should all take my comments with this in mind.
16:44:03 <acozine> tadeboro: heh, understood; i htink you are actually bearing it quite well
16:44:11 <acozine> felixfontein: yes, I think that's our best approach
16:44:24 <abadger1999> felixfontein: +1
16:44:35 <acozine> at least it gives community collection owners and contributors the ability to add docs somewhere
16:45:18 <felixfontein> tadeboro: have you tried using a rst -> markdown converter?
16:46:04 <acozine> (cyb-clock says we're 45 minutes into the meeting)
16:46:13 <samccann> heh
16:46:33 <tadeboro> Yes. And the pandoc did not produce the best results. So we decided to only write them in md and call it a day.
16:47:00 <felixfontein> ok, so we basically have two choices (if we ignore galaxy): we try to use Markdown right away (so the same docs work with AH), or we use RST. (or allow both? no idea how well that works with sphinx though, I only ever used it with RST.)
16:47:01 <acozine> tadeboro: do your collections have the same name for Galaxy and for AH?
16:47:43 <tadeboro> The ones I have influence over, yes. The ones I help to write for Red Hat: no idea, how they will be named in galaxy.
16:48:11 <abadger1999> felixfontein: Pretty  sure that sphinx cannot use md.
16:48:16 <acozine> so a community person could, in theory, add rst docs as well as the md
16:48:47 <samccann> I think the current proposal has them in two different areas in the /docs folder - md is in /docs directly, and rst in /docs/docsite/rst
16:49:00 <tadeboro> abadger1999: Shinx can use md, but this limits the capabilities quite severly.
16:49:05 <abadger1999> We can add a step to  convert from md to rst as part of our tooling.  But we'd still loose out on the sphinx/rst markup (module links and so forth)
16:49:07 <samccann> so the pipeline update that would bring them back to docs.ansible.com will only look at /docs/docsite/rst
16:49:17 <joelouthan> #unchair
16:49:17 <zodbot> Current chairs: abadger1999 acozine baptistemm dericcrago felixfontein joelouthan samccann tadeboro
16:49:25 <felixfontein> bye joelouthan!
16:49:29 <acozine> #unchair joelouthan
16:49:29 <zodbot> Current chairs: abadger1999 acozine baptistemm dericcrago felixfontein samccann tadeboro
16:49:43 * acozine waves
16:50:01 <tadeboro> I would say we at least give community a place to put their rst files that should be rendered on docs.ansible.com
16:50:08 <acozine> yes, I agree
16:50:13 <tadeboro> Anything else is probably not doable by us alone.
16:50:23 <acozine> after all, in a year or two we may have some third option
16:50:32 <felixfontein> abadger1999: it's probably best if collection maintainers convert md to rst themselves if they want to convert it - that simplifies the pipeline and avoids many potential problems that will get blamed on us ;)
16:50:33 <acozine> no technology lasts forever
16:50:36 <abadger1999> ah, this recommonmark extension?
16:51:34 <abadger1999> felixfontein: <nod>
16:51:48 <abadger1999> And we can always start there and look into something automatic later.
16:51:57 <abadger1999> Better to add features than to take away.
16:52:02 <acozine> heh, yep
16:52:04 <felixfontein> abadger1999: yes!
16:52:18 <acozine> we can also test any conversions on content we know well
16:52:21 <acozine> to see what the pitfalls are
16:53:34 <acozine> sounds like we are (mostly?) reaching consensus
16:53:41 <acozine> shall we have a quick vote?
16:53:56 <felixfontein> I guess the next step would be defining the exact directory, and the exact requirements :)
16:53:59 <felixfontein> vote sounds good
16:55:12 <acozine> Proposal:  allow rst files in the collection /docs/docsite/rst/ folder, require an index.rst file there, and publish all docs from there to docs.ansible.com under the collection; next step is to define exact requirements
16:55:37 <abadger1999> Oh, one question.
16:55:54 <felixfontein> hmm, why an index.rst file? what should it contain and where will it end up?
16:56:08 <abadger1999> on docs.ansible.com, there is already a docs.a.c/[..]/collections/ansible/posix/index.html.   Where will this new index.rst end up?
16:56:32 <felixfontein> I'd prefer a mechanism to add new entries to the existing index.rst file
16:56:37 <acozine> index.rst is the default page for any directory
16:56:41 <acozine> ah, I see
16:56:59 <acozine> I was thinking the /docs/docsite/rst/index.rst would come out as something like
16:57:31 <acozine> docs.a.c/ansible/4/collections/ansible/posix/user_guide/index.html
16:57:41 <tadeboro> I would assume index will be generated and would contain links to docs generated from rst files + link to reference material.
16:57:53 <acozine> yeah, we already generate that top-level index page
16:58:47 <acozine> I envisioned a link at the top called something standard (like User Guide) on https://docs.ansible.com/ansible/latest/collections/ansible/posix/index.html#plugins-in-ansible-posix
16:58:50 <felixfontein> acozine: user_guide sounds too specific IMO
16:58:58 <acozine> okay
16:59:15 <acozine> we can come up with something more generic
16:59:21 <felixfontein> for example in my collections, I'd like to add reference material for roles and test/filter plugins
16:59:34 <acozine> we could just use `collection_documentation` or something
16:59:40 <felixfontein> would be strange if that ends up under "user guide", while all other plugins are documented somewhere else
16:59:53 <felixfontein> `docsite/`? :)
17:00:04 <acozine> sure
17:00:04 <felixfontein> (that's what my current WIP uses ;) )
17:00:13 <abadger1999> For felixfontein 's idea, the simplest implementation would probably to use a sphinx include
17:00:15 <acozine> ah, that makes it even easier
17:00:27 <acozine> and it's also recursive, which makes it kinda fun
17:00:42 <acozine> oops, we're at time
17:00:51 <acozine> and I'm about to be late for my next meeting
17:00:55 * samccann needs to drop.. later everyone!
17:01:01 <acozine> bye samccann
17:01:01 <samccann> #unchair samccann
17:01:01 <zodbot> Current chairs: abadger1999 acozine baptistemm dericcrago felixfontein tadeboro
17:01:05 <felixfontein> abadger1999: you mean including index.rst into the generated one?
17:01:14 <felixfontein> bye samccann!
17:01:28 <abadger1999> felixfontein: yeah.... but probably don't use index.rst as the name to avoid confusion
17:02:00 <acozine> can we do a quick open floor and close the official meeting?
17:02:09 <felixfontein> maybe something like `_include.rst`?
17:02:18 <felixfontein> acozine: sure
17:02:19 <abadger1999> You can look at the mechanism used for things like this, for isntance: https://github.com/ansible/ansible/blob/devel/docs/docsite/rst/shared_snippets/download_tarball_collections.txt
17:02:27 <abadger1999> felixfontein: yeah
17:02:36 <acozine> the thing about index.rst is that it's where the webserver lands you by default if you hit a directory URL
17:02:57 <felixfontein> acozine: yep, that's why it should not be included, because it is already a standalone site
17:03:54 <acozine> I'm not sure I follow
17:04:04 <acozine> but I'll look at the discussion again
17:04:11 <acozine> after my next meeting
17:04:29 <abadger1999> Cool.  open floor sounds good
17:04:31 <acozine> changing the time back next wek will give me more flexibility
17:04:31 <felixfontein> acozine: index.rst should end up as https://docs.ansible.com/ansible/latest/collections/ansible/posix/docsite/index.html, while _include.rst should end up included in the auto-generated https://docs.ansible.com/ansible/latest/collections/ansible/posix/index.html
17:04:37 <acozine> #topic open floor
17:04:49 <acozine> anybody have a PR they'd like eyes on?
17:04:55 <acozine> or a question to ask?
17:05:06 <acozine> need advice on something?
17:05:23 <acozine> filed an issue, need help, etc.?
17:05:46 <acozine> everyone welcome to post any comments, ideas, topics, suggestions, questions . . . anything really
17:05:48 <acozine> the floor is open
17:06:02 <acozine> general reminder: chat is welcome in the channel at any time
17:06:20 <acozine> we may not have folks here in some hours of the day/night
17:06:39 <acozine> but we will answer when we're awake and online again if you ask when nobody's around
17:06:43 <acozine> also
17:07:07 <acozine> items for the official agenda are always welcome, just add a comment to https://github.com/ansible/community/issues/579
17:07:18 * acozine gives it one more minute
17:08:10 <acozine> okay, thanks everybody!
17:08:19 <acozine> see you next week
17:08:26 <acozine> UTC time will be one hour earlier
17:08:29 <abadger1999> Thanks for running the meeting!
17:08:38 <acozine> depending on your local time, that may be the same time, or an hour earlier
17:08:41 <acozine> #endmeeting