16:02:10 <acozine> #startmeeting Docs Working Group aka DaWGs
16:02:10 <zodbot> Meeting started Tue Mar 16 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 acozine. 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 'docs_working_group_aka_dawgs'
16:02:14 <acozine> #topic opening chatter
16:02:16 * samccann waves
16:02:16 <acozine> who's around?
16:02:21 <tadeboro> o/
16:02:28 <acozine> #chair samccann tadeboro abadger1999
16:02:28 <zodbot> Current chairs: abadger1999 acozine samccann tadeboro
16:02:43 <lmodemal> DING DING DING!  DaWGs (documentation working group meeting) happening now https://github.com/ansible/community/issues/579
16:02:53 <acozine> #chair lmodemal
16:02:53 <zodbot> Current chairs: abadger1999 acozine lmodemal samccann tadeboro
16:03:33 <lmodemal> Hello everyone
16:03:46 <acozine> andersson007_: dericcrago dmsimard gundalow baptistemm briantist cyberpear felixfontein jmn madonius mrproper tremble tributarian you folks chatting docs today?
16:04:11 <briantist> kinda sorta barely (in another meeting at usual)
16:04:23 * dericcrago waves
16:04:38 <acozine> briantist: bummer, do you want to be furniture? or just lurk?
16:04:42 <acozine> #chair dericcrago
16:04:42 <zodbot> Current chairs: abadger1999 acozine dericcrago lmodemal samccann tadeboro
16:05:31 <acozine> today's agenda begins with https://github.com/ansible/community/issues/579#issuecomment-789144801
16:06:26 <felixfontein> hi!
16:06:34 <acozine> #chair felixfontein
16:06:34 <zodbot> Current chairs: abadger1999 acozine dericcrago felixfontein lmodemal samccann tadeboro
16:06:38 <acozine> hi felixfontein
16:07:10 <briantist> chair is ok, helps me pay attention to something a little if possible
16:08:04 <acozine> #chair briantist
16:08:04 <zodbot> Current chairs: abadger1999 acozine briantist dericcrago felixfontein lmodemal samccann tadeboro
16:10:26 <acozine> if I didn't mention your nickname, you are still welcome to join the meeting and be a chair! if you haven't participated recently, we try not to annoy you with pinging
16:11:06 <acozine> wave at any time and we will make you a chair
16:11:42 <acozine> #topic collection /docs/ folder usage
16:12:01 <acozine> I have an update and we have a proposal on this topic
16:12:38 <felixfontein> did we make any progress on who needs to actually be involved in that decision? :)
16:12:45 <acozine> a little, yes
16:12:50 <felixfontein> \o/
16:13:00 <acozine> we got a firm commitment that existing docs will remain on docs.ansible.com
16:13:23 <acozine> so we can craft a pipeline to publish the material that's now in Scenario Guides from collections
16:13:52 <felixfontein> scenario guides, and potentially more, I guess?
16:14:11 <acozine> if collection owners want to add things in rst, I think we can publish them
16:14:42 <acozine> for Galaxy, the focus will be on presenting documentation in the GUI, and it will likely be markdown
16:15:15 <samccann> hmm
16:15:24 <tadeboro> Ugh, this makes it really awkward for people writing docs.
16:15:36 <samccann> so this means the collection owner has to decide - markdown if they want docs in Galaxy, rst if they want them on docs.ansible.com?
16:15:45 <felixfontein> samccann: or both for both :)
16:15:50 <samccann> heh yeah
16:16:00 <tadeboro> It is hard enough to write the docs once, and now I need to author rST and md ... Not fun.
16:16:19 <acozine> it's certainly not ideal
16:16:44 <felixfontein> I guess I'd use a rst -> markdown converter for the galaxy docs, once galaxy actually supports docs
16:16:48 <acozine> but remember that right now, Galaxy doesn't show anything
16:16:55 <acozine> (community Galaxy)
16:17:00 <samccann> are the Powers That Be open to the idea of us bringing any markdown in the /docs collection folder back to docs.ansible.com (assuming some clever person can convert md to rst )?
16:17:00 <felixfontein> does galaxy plan to automatically render plugin/module docs?
16:17:29 <tadeboro> felixfontein: I would say yes since galaxy_ng/AH already does that.
16:17:36 <acozine> once community galaxy adopts the galaxyNG code, yes
16:17:38 <samccann> as in - everything in /docs is written as md
16:17:55 <samccann> and then we convert and bring back to docs.ansible.com for the included collections
16:18:06 <abadger1999> there are programs to convert rst to md and md to rst (pandoc, for instance).  rst contains more information than md, though, so converting from rst => md is probably better than the other way around.
16:18:11 <samccann> (and we'd also go rst > md to move the existing guides out of docs.ansible.com
16:18:21 <abadger1999> I don't know if any of the converters handle sphinx's extensions to rst well.
16:18:35 <felixfontein> samccann: that sounds horrible :) also MD does not support references
16:19:01 <samccann> abadger1999 - in general, AH/Galaxy-ng afaik only supports a subset of md. So yeah, it's quite limiting right now. Dunno the roadmap tho
16:19:03 <felixfontein> samccann: scenario guides tend to reference modules/plugins, and all these references will die on conversion
16:19:33 <samccann> having docs split between docs.ansible.com and galaxy/AH gui is also, imo horrible
16:19:39 <acozine> yeah, I think we move the scenario guides to an rst subdirectory, keeping them in rst format
16:19:55 <tadeboro> The latest collection I was helping with (https://github.com/ansible-collections/servicenow.itsm) has one big mess of a docs folder right now. My team authored the developer guidelines in md because this is meant to be certified, and to give community ability to see the reference material, module docs are rendered into rst.
16:20:25 <acozine> tadeboro: I think that may be a common pattern for certified collections in future
16:20:47 <felixfontein> tadeboro: the .rst module/plugin docs seem to be pretty common in quite some collections, like ansible.posix or amazon.aws (as two random examples)
16:21:00 <samccann> as I recall, the only reason .rst for module docs is because galaxy doesn't display them yet
16:21:16 <felixfontein> acozine: the .rst files in these collections are not really needed by docs.ansible.com either, since we auto-generate plugin docs
16:21:28 <tadeboro> felixfontein: These are not completelly random since they are all maintained primarily by Red Hat with a common set of tools.
16:21:30 <samccann> yeah they are there only for galaxy users
16:22:01 <felixfontein> tadeboro: I randomly picked two of them, I didn't want to imply that a 'random' set of collections does that :)
16:23:04 <tadeboro> Anyhow, before I derail everyting, being able to author scenario guides in rST and have them published on docs.ansible.com sounds like a great start.
16:23:14 <acozine> oh, I misunderstood, the module docs for those collections are being written in rst directly, not generating rst from `DOCUMENTATION` strings in the python files?
16:23:30 <felixfontein> acozine: they are auto-generated from DOCUMENTATION
16:23:46 <felixfontein> tadeboro: I agree. also having other docs, like for filter/test plugins and for roles...
16:23:59 <bcoca> most plugin/module docs are written in YAML embeded in ,py files as variables
16:24:13 <tadeboro> They are generated from the code and then commited to the repo because right now, only AH renders them (if the collection is not part of the ansible package).
16:24:30 <acozine> oh, I see what you mean
16:25:12 <samccann> perhaps we can list some pros n cons to having a docs/rst/xxx folder in a collection?
16:25:39 <samccann> might help me see how the pros outway the big con of rst vs md for collection authors
16:25:43 <samccann> (or both)
16:25:50 <acozine> so those docstrings are still maintained in the .py files, then you render them into rst and commit those to the repo for AH to show as well as adding them to docs.ansible.com using the usual methods
16:26:04 <samccann> for Galaxy to show, yeah
16:26:04 <bcoca> 2 things to consider a) self hosting by collections b) ansible docsite/galaxy/AH hosting
16:26:13 <samccann> AH already shows them from .py
16:26:41 <abadger1999> acozine: yes
16:26:45 <samccann> a) self hosting, b) ansible docsite, and c) Galaxy AH hosting
16:26:50 <felixfontein> samccann: galaxy does not show the .rst files, but the collections README links to them on github
16:27:02 <samccann> what's on galaxy-ng/ah does not show up on docs.ansible.com
16:27:20 <bcoca> samccann: i was hoping doscite and galaxy/ah could agree to standard, but yes, in the end 3 diff ones
16:27:35 <samccann> felixfontein - yeah my point was AHdoesn't need those module rst files
16:27:52 <samccann> bcoca - was my hope as well but seems that ship sailed/is sailing
16:28:20 * bcoca commisions submarine to brings ships back in line or force reconstruction
16:28:31 <samccann> bcoca - which is also why, if Galaxy/AH can't handle .md, I was suggesting maybe we need to be the ones to bend on this and go to .md for scenario guides etc
16:28:36 <acozine> I think if we have 2 options, then collection owners who self-host can choose one of those two
16:29:17 <samccann> self-hosters can do whatever they want imo. May not even be in /docs folder, might be their own corp site or aything else
16:30:06 <acozine> for me, the two big advantages of having an rst subdirectory are: 1) we don't have to convert existing content, some of which is out of date, so I hate to spend a lot of cycles on it, and 2) we preserve internal links (and the ability to add internal links in future content, if collection owners choose to do so)
16:30:23 <tadeboro> What we ended up doing is self-hosting the docs (complete Sphinx site) and put links to the online docs into md files for AH users.
16:30:33 <felixfontein> acozine: +1
16:30:53 <samccann> acozine - that's all bennies to us
16:31:08 <felixfontein> samccann: 2) is also a huge benefit for collection docs authors
16:31:10 <samccann> what bennies are there to collection developers? What bennies to users
16:31:25 <felixfontein> samccann: being able to use references is the main reason for RST imo :)
16:31:29 <acozine> I'd say 2) is a benefit to users
16:31:33 <samccann> felixfonein - so that's a user bennie as well (hotlinks that work ;-)
16:31:38 <felixfontein> 2) is a benefit for everyone
16:31:53 <felixfontein> also collection devs have an easy way to reference plugins
16:32:05 <felixfontein> without having to guess / care about URLs
16:32:21 <acozine> short-term, collection owners also benefit from having a way to add docs above and beyond the module/plugin docs in a place where community users can access them
16:32:33 <acozine> since right now Galaxy can't display it
16:32:36 <samccann> so the cons  - 1) developers have to use 2 docs languages if they want docs in both places. 2) user will always have to check both places (docs.ansible.com and AH) to find complete docs for the collections because they won't know if either is complete
16:32:44 <tadeboro> Links to reference material (module docs) is where md falls flat on its face right now.
16:33:02 <acozine> though as tadeboro mentioned, collection owners can self-host their docs and link to that site from the main collection README
16:33:28 <tadeboro> Galaxy even offers docs site link in the top-right corner somewhere IIRC.
16:33:39 <acozine> oh, right, I forgot about that
16:34:06 <samccann> my personal fear - developers will see the benefit of having their docs come over to docs.ansible.com, so won't write in .md, but will write in rst. All well and good, but then the 'vision' for AH fails because it will never have complete docs per collection there
16:35:02 <felixfontein> samccann: or the AH/galaxy_ng team thinks again about the decision to stick only to MD :)
16:35:08 <samccann> heh
16:35:42 <samccann> ok in general, I can't +1 this idea, but y'all have convinced me to be a neutral 0 instead of a -1
16:35:49 * samccann loves to talk in irc vote-speak
16:35:50 <felixfontein> :)
16:36:00 <abadger1999> AH could either deal with rst or it could run pandoc to convert rst to md.
16:36:04 <abadger1999> on import
16:36:57 <acozine> or do the GitHub-style rst half-display
16:37:23 <abadger1999> <nod> yeah, that would be dealuing with rst.
16:37:34 <acozine> ah, heh
16:39:29 <tadeboro> From my experience, if one wants to deliver great user experience, self-hosting is the only option.
16:39:58 <tadeboro> Because even if we go with rST for scenario gudes, we will probably need to limit the features developers can use.
16:40:30 <acozine> perhaps in a few years the collection index on docs.ansible.com will be a set of links to self-hosted sites elsewhere
16:41:01 <tadeboro> For example, https://github.com/sensu/sensu-go-ansible/blob/master/docs/source/quickstart-sensu-go-6.rst uses to create download links and render examples.
16:41:43 <tadeboro> And I am not sure how well this would work in community scenario where files from collections are moved into one place and rendered.
16:43:12 <felixfontein> tadeboro: right now (in my WIP) only files from docs/docsite/rst are copied, if you include files from somewhere else it won't work
16:43:52 <acozine> tadeboro: we have some download links in the main docs - see https://github.com/ansible/ansible/blob/devel/docs/docsite/rst/network/getting_started/first_playbook.rst
16:44:40 <felixfontein> I guess the main problem is that the files need to be around for that. but that should be solvable
16:44:48 <acozine> yeah
16:45:51 <acozine> we don't want to discourage self-hosting
16:46:32 <acozine> but we want to allow other options
16:47:01 <acozine> shall we look at felix's WIP PR? https://github.com/ansible-community/antsibull/pull/255
16:47:02 <github-linkbot> https://github.com/ansible-community/antsibull/pull/255 | open, created 2021-03-06T19:52:36Z by felixfontein: [WIP] Allow collections to add RST files
16:47:54 <felixfontein> the PR is somewhat minimal in the sense that it will only handle .rst files (and no other files in that directory) which satisfy all conditions (i.e. labels have a specific prefix)
16:48:24 <tadeboro> I think rendering some rst files to docs.ansible.com would benefit collection developers that do not have the bandwidth to maintain the docsite themself. Writing a rST file is ay simpler compared to maintaining Sphinx site.
16:48:30 <felixfontein> but it's flexible enough to improve some collection docs a lot :)
16:48:57 <felixfontein> tadeboro: indeed!
16:49:26 <acozine> ooh, this covers filter docs too!
16:49:27 <acozine> https://ansible.fontein.de/collections/felixfontein/tools/
16:50:27 <felixfontein> acozine: it basically allows you to add some sections and mention what should be in them :)
16:50:55 <acozine> oh, no! we didn't run the cyb-o-clock and now it's ten minutes to the end of the meeting
16:50:59 <felixfontein> https://github.com/felixfontein/ansible-tools/compare/docs#diff-1581b6b05d6f713e6fa7078d9ed1cd1202ac5842aff67635839e3faf7276c54f
16:51:08 <felixfontein> that's the 'toc' file
16:52:18 <samccann> ooch!
16:52:20 <acozine> the approach is minimal, and it's also easy to describe and document
16:52:33 <samccann> oh we didn't minute anythingeither...
16:52:37 <acozine> heh
16:52:47 <acozine> we miss one meeting and we get totally out of practice!
16:52:50 <samccann> can you and an appropriate agreed? or at least an info
16:53:07 <acozine> I guess we didn't actually vote
16:53:42 <samccann> ok a quick vote would help, then we can agreed it so it shows up in the minutes
16:53:44 <acozine> VOTE: designate a subdirectory of the collection /docs/ folder for rst docs that we will publish to docs.ansible.com
16:53:47 <acozine> #chair
16:53:47 <zodbot> Current chairs: abadger1999 acozine briantist dericcrago felixfontein lmodemal samccann tadeboro
16:53:55 <acozine> please vote on ^^^
16:54:11 <abadger1999> +1
16:54:17 <acozine> +1
16:54:19 <tadeboro> +1
16:54:21 <samccann> 0
16:54:28 <lmodemal> +1
16:54:32 <felixfontein> +1
16:55:20 <acozine> 6 of 8 chairs voted; tally is +5
16:55:43 <acozine> #agreed designate a subdirectory of the collection /docs/ folder for rst docs and publish them to docs.ansible.com
16:56:22 <felixfontein> btw I used docs/docsite/rst because someone two weeks ago mentioned it would be nice to have the same path as in ansible/ansible. there's no deeper reason behind it ;)
16:56:24 <acozine> felixfontein: what would be most helpful in getting https://github.com/ansible-community/antsibull/pull/255/files out of WIP mode?
16:57:07 <acozine> felixfontein: I think that was me, i figured it was both familiar enough to be useful and deep enough down to allow other uses of /docs/ in future
16:57:27 <felixfontein> acozine: it's WIP because it's a proposal which makes several decisions that should be made officially, like the directory name, the index.yml file, the concrete label prefix, ...
16:57:57 <felixfontein> acozine: besides that, it works well enough for my testing :)
16:57:58 <samccann> docs/docsite/ does suggest 'these rst files are going someplace special)
16:58:09 <acozine> okay, so next week we should be a bit more organized and review those decisions
16:58:51 <tadeboro> docsite also do not clashes with thigs like source and build that standalone Sphinx sites often use.
16:59:17 <acozine> excellent, it will allow collection owners lots of flexibility
16:59:30 <tadeboro> docsite also does not clashe with thigs like source and build that standalone Sphinx sites often use. (/me is bad at grammar today)
16:59:33 <felixfontein> acozine: sounds good!
16:59:45 <acozine> okay, I have one minute
16:59:50 <acozine> #open floor
16:59:53 <acozine> er
16:59:54 <acozine> oops
17:00:01 * acozine is REALLY out of practice
17:00:04 <acozine> #topic open floor
17:00:46 <acozine> all questions/comments/ideas/suggestions/complaints welcome
17:01:11 <samccann> I have a PR I'm reviewing I'd like some quick thoughts on
17:01:15 <acozine> great!
17:01:23 <samccann> https://github.com/ansible-collections/community.mysql/pull/112/files
17:01:34 <felixfontein> ah, that one :)
17:01:45 <samccann> i have basically a meta question - should we be putting this much detail into the contributor.md of a bunch of collections?
17:01:56 <samccann> It seems a repeat of what is in the docs for 'core'.
17:02:02 <samccann> Though with more detail etc
17:02:20 <samccann> so not looking for nitty gritty feedback, but 'is this the right direction' feedback
17:02:44 <samccann> andersson007_ ^^
17:03:05 <samccann> cyb-clock - we are 1 hr 2 min into the meeting
17:03:20 <tadeboro> I would say "yes if the collection does things in its own way".
17:03:45 <tadeboro> We have a whole hacking subsection in https://sensu.github.io/sensu-go-ansible/hacking.html
17:04:12 <samccann> yeah the proposal is to use this PR to eventually create a 'template' version of it all for people creating colections (and I'd guess a bunch of existing ansible or community collections we all know and love
17:04:23 <samccann> I'm fine w/ a collection having something for when they do things their own way.
17:04:40 <tadeboro> This allows people that are not familiar with the codebase to start contributing with as little effort as possible.
17:04:51 <felixfontein> having some template at least for most community collections would be really helpful
17:04:53 <samccann> I guess the alternate would be we specify on docs.ansible.com that it covers only core contributions and see the collection for how to contribute there
17:04:59 <felixfontein> it doesn't make sense to write that stuff multiple times :)
17:05:48 <felixfontein> samccann: I think docs.ansible.com should also have some (basic) instructions on how to check out a collection repo and work with it
17:05:50 <samccann> ok if folks feel this direction is fine, cool
17:06:03 <samccann> i just wanted to ask before I complete my review
17:06:20 <tadeboro> I do not mind having copies all over the place becase those documents are instructions on how to contribute to a particular collection. But in case of community collections that all follow roughly the same procedures, then this information can be placed somewhere centrally.
17:08:25 <samccann> ok are there any other open topics?
17:08:45 <samccann> now's your chance.. .bring up docs ideas, PRs, issues, favorite .rst files etc ;-)
17:09:32 <felixfontein> or wait until next week ;)
17:09:57 <samccann> heh
17:10:01 <samccann> ok not hearing much
17:10:14 <samccann> gonna end the meeting in a minute if nobody screams
17:11:12 <samccann> #endmeeting