14:31:28 <samccann> #startmeeting Documentation Working Group aka DaWGs
14:31:28 <zodbot> Meeting started Tue Nov 10 14:31:28 2020 UTC.
14:31:28 <zodbot> This meeting is logged and archived in a public location.
14:31:28 <zodbot> The chair is samccann. Information about MeetBot at http://wiki.debian.org/MeetBot.
14:31:28 <zodbot> Useful Commands: #action #agreed #halp #info #idea #link #topic.
14:31:28 <zodbot> The meeting name has been set to 'documentation_working_group_aka_dawgs'
14:31:36 <acozine> o/
14:31:50 <samccann> oh thank the lord... I can't remember half the commands!
14:32:00 <acozine> heh
14:32:07 <acozine> #topic opening chatter
14:32:13 <acozine> hmmm
14:32:53 <acozine> apparently I can't either? or else freenode is having a bad day
14:33:05 <acozine> #topic welcoming chatter
14:33:08 <acozine> nope
14:33:18 <acozine> oh, well
14:33:21 * gundalow waves
14:33:23 <dmsimard> o/
14:33:27 <acozine> freeform meeting i guess ;-)
14:33:27 <felixfontein> soe #chair are needed
14:33:28 <dericcrago> hi
14:33:38 <acozine> heh
14:33:43 <acozine> I can't chair until I am a chair
14:33:51 <samccann> #chair acozine
14:33:51 <zodbot> Current chairs: acozine samccann
14:33:56 <acozine> thanks!
14:34:00 <samccann> sorry about that!  rough start ;-)
14:34:05 <felixfontein> sorry for my typing, my internet connection decided to go up to 40% package loss, so everything is a bit laggy for me
14:34:22 <acozine> #chair dericcrago gundalow felixfontein dmsimard lmodemal
14:34:22 <zodbot> Current chairs: acozine dericcrago dmsimard felixfontein gundalow lmodemal samccann
14:34:51 * acozine tries to set the topic now that power has gone to her head . . .
14:34:56 <acozine> #topic opening chatter
14:35:02 <acozine> there we go - thanks felixfontein
14:35:13 <acozine> (for the pointer)
14:35:48 <felixfontein> brb restarting router
14:35:53 <felixfontein> resp. modem
14:36:16 <acozine> who else is around? andersson007_ briantist cyberpear madonius mrproper tadeboro Tas-sos tremble tributarian you folks talking docs today?
14:36:45 * tremble is lurking but in other meetings
14:37:05 <tadeboro> I am here but have not yet looked at the agenda for today.
14:37:07 <acozine> tremble: cool, do you want to be a chair?
14:37:13 <acozine> #chair tadeboro
14:37:13 <zodbot> Current chairs: acozine dericcrago dmsimard felixfontein gundalow lmodemal samccann tadeboro
14:37:14 <tremble> nah
14:37:21 * acozine nods
14:37:35 <acozine> tadeboro: neither have I . . . we'll all look together
14:38:35 <samccann> #info agenda https://github.com/ansible/community/issues/521#issuecomment-721211831
14:39:07 <acozine> plus following comments
14:39:41 <samccann> yep
14:40:03 <felixfontein> re
14:40:05 <acozine> #topic version split and supplementary meeting
14:40:25 <acozine> quick summary:
14:40:59 <acozine> when Ansible (the package on PyPI) releases version 2.11, we will have a version split that we must reflect somehow in the documentation
14:41:42 <acozine> because Ansible 2.11 will be based on ansible-core 2.10, and then we will also have ansible-core 2.11 sometime in spring
14:42:01 <felixfontein> is the new name ansible-core final now
14:42:01 <felixfontein> ?
14:42:10 <acozine> felixfontein: ah, no
14:42:16 <felixfontein> ok :)
14:42:18 <felixfontein> sorry to interrupt
14:42:24 <acozine> at least, not so far as I know . . .
14:42:47 <acozine> anyway, soon we will have two different things with the same version number
14:43:35 <acozine> this is a challenge for documentation, and since it's also an opportunity, we have added a weekly meeting here in IRC just to discuss possible solutions
14:43:42 <acozine> that meeting is on Thursdays
14:44:05 <samccann> #info Thurs supplemental meeting minutes from last week - https://github.com/ansible/community/issues/521#issuecomment-721211489
14:44:06 <acozine> it starts at UTC one hour later than this current meeting
14:44:07 <tremble> I hate so suggest it but should the *name* of one of the 'Ansible's change to something completely different...
14:44:35 <tremble> Not your call, but it's really going to get painful.
14:44:40 <acozine> tremble: that is a possible solution, or part of one
14:44:51 <samccann> #info weekly Thurs supplemental meeting starts 10:30am ET on #ansible-docs to cover splitting the docsite
14:45:37 <acozine> no matter what happens with the naming convention, even if we announce a new name for one of the things, we have to figure out how to split up the documentation
14:45:37 <felixfontein> I second tremble. but that's nothing this meeting can decide I guess :)
14:46:13 <acozine> let's say we announce that the code formerly known as ansible-core will now be known as fumblefluff
14:46:14 <samccann> #info folks are getting confused between ansible-base and Ansible (the names are too similar)  -someone somewhere might want to consider renaming one of them
14:46:57 <acozine> we still need to have a plan for documenting fumblefluff features and Ansible features, and helping people understand which bits are fumblefluff and how the fumblefluff version relates to the Ansible version and so on
14:47:15 <acozine> a new name would help with public understanding
14:47:31 <acozine> but it doesn't solve all the documentation challenges
14:47:36 <samccann> We should probably leave that to Thursday's meeting or it will fumblefluff its way through the entire hour here :-)
14:48:09 <acozine> samccann: true . . .
14:48:47 <acozine> if you can, please join us on Thursday as we debate the question of which docs belong where, how to organize the docsite, what happens to the version-switcher, and more related questions
14:48:49 <acozine> bring your friends
14:48:53 <acozine> all are welcome!
14:49:15 <acozine> #topic removing docs files from Ansible tarballs
14:49:53 <samccann> it seemed like we were in agreement, at least on Ansible the package, but maybe we needed someone to give it a test run and see if there were complications?
14:49:59 <acozine> IIRC we ended last week by agreeing that we would like to distribute an `ansible-docs` tarball separate from the `ansible` tarball
14:50:11 <felixfontein> I think so
14:50:25 <felixfontein> do we also want an ansible-base-docs tarball next to the ansible-base tarball?
14:50:35 <acozine> probably
14:50:44 <samccann> speaking of nameing, it shouldn't be the ever so convenient `ansible-docs` or we will continue the confusion of it relating to `ansible-docs` the command
14:51:06 <acozine> I think the more we set a pattern and stick to it everywhere, the less confusing this will be
14:51:18 <acozine> ^^^ was in response to felixfontein
14:51:32 <samccann> fumblefluff-docs FTW~~~
14:51:32 <bcoca> ansible-manual
14:51:43 <samccann> or ansible-documentation
14:51:58 <felixfontein> for system packages, the naming schema *, *-docs, *-src is pretty common I think
14:52:00 <samccann> ansible-rtfm
14:52:01 <bcoca> ansible-rtfm
14:52:06 <bcoca> jinx!
14:52:08 <samccann> hahah JINX!
14:52:10 <acozine> heh
14:52:13 <samccann> dagnammit!
14:52:43 <samccann> other than deciding a spiffy name, is there anything we need to discuss or is it just 'find a volunteer' to give it a try?
14:53:31 <felixfontein> what should the tarballs contain? just the .rst files? also .html files? or even more formats?
14:53:38 <bcoca> felixfontein: when a couple of distros shipped ansible-docs with the html versions it caused much confusion .. just like the current naming of the main packages, i would try to do LESS of that
14:54:02 <acozine> bcoca: what kind of confusion?
14:54:09 <bcoca> felixfontein: the -docsrc for rst the others we can do by format ansible-dochtml ?
14:54:10 <felixfontein> bcoca: did people assume that `ansible-doc` (tool) is contained in `ansible-docs` (package)?
14:54:20 <bcoca> acozine: peopel refering to the package thinkging it provided the cli
14:54:26 <bcoca> felixfontein: exactly
14:54:43 <felixfontein> meh. people are always good at ignoring missing/extra letters.
14:55:17 <samccann> So I think we can avoid the tool confusion by giving it another name.
14:55:31 <samccann> We could even use `ansible-html` and include the rst files inside it
14:55:38 <bcoca> felixfontein: people just as easily plurialize the singular by mistake
14:56:07 <felixfontein> I guess packagers might rename it back to -docs anyway, since naming it otherwise would break convention in the packaging world. but no idea...
14:56:23 <acozine> hmm, how about `ansible-docs-html` - otherwise it's not clear what the content is
14:56:29 <bcoca> ansible-html-docs
14:56:34 <felixfontein> ansible-docs-rst, ansible-docs-html, ...?
14:56:36 <acozine> or ^^^
14:56:43 <acozine> yeah, I like that
14:56:58 <bcoca> the docs end matches the convention, adding type in the middle will ensure users READ that part
14:56:59 <acozine> though it does ruin autocomplete
14:57:12 <bcoca> just for package install .. im fine with that
14:57:20 <felixfontein> I prefer -docs-<format> so that if you sort alphabetically, they are grouped if other ansible-* packages are around
14:57:21 <bcoca> since it wont create actual binaries in shell
14:57:41 <bcoca> felixfontein: but as you mentioned, that would violate many distro naming conventions
14:57:49 <bcoca> though i've seen it both ways
14:57:50 <samccann> #info need to be careful on naming the docs package so no one confuses it with `ansible-docs` the cli command.
14:58:15 <tadeboro> s/ansible-docs/ansible-doc/ ;)
14:58:19 <samccann> so there is a sort of convention of docs packages being named fumblefluff-docs ?
14:58:37 <acozine> what are the odds that packagers will rename them `ansible-docs-html-docs` and `ansible-docs-rst-docs`?
14:58:44 <samccann> #uninfo
14:58:48 <felixfontein> #undo
14:58:48 <zodbot> Removing item from minutes: INFO by samccann at 14:57:50 : need to be careful on naming the docs package so no one confuses it with `ansible-docs` the cli command.
14:58:52 <bcoca> acozine: high ...
14:58:54 <bcoca> sadly
14:59:00 <acozine> heh
14:59:03 <acozine> I was joking
14:59:08 <acozine> but actually I'd be fine with that
14:59:09 <samccann> #info need to be careful on naming the docs package so no one confuses it with `ansible-doc` the cli command
14:59:33 <felixfontein> I think I prefer ansible-docs-html-docs over ansible-html-docs
14:59:39 <acozine> me too
14:59:52 * bcoca adds note to 'things to cry about' list
14:59:58 <acozine> awww
15:00:03 * acozine passes tissues to bcoca
15:00:07 <samccann> i'm missing  the need for the docs in the middle?
15:00:09 <lmodemal> lol
15:00:23 <samccann> to me, it starts once again to confuse it with `ansible-doc` command
15:00:24 <bcoca> samccann: its a sorting issue when listing packages
15:00:26 <felixfontein> samccann: grouping when package names are sorted alphabetically
15:00:42 <samccann> ah ok
15:00:46 <bcoca> but i think that better name > sorting issue, just mho
15:00:49 <acozine> samccann: we're speculating that a package maintainer, given a package named something that doesn't end with `docs` will tack `docs` onto the end "because docs packages always end with `-docs`"
15:00:58 <felixfontein> then ansible-core isn't between ansible-ascii-docs and ansible-html-docs ;)
15:01:23 <bcoca> felixfontein: ascii-docs are included in core!
15:01:45 <felixfontein> bcoca: then take a random other docs file format that comes alphabetically before c
15:01:54 * acozine adds `ascii-docs` to her own list of 'things to cry about'
15:01:55 <bcoca> you mean asciidoc-docs
15:02:21 <samccann> LOL!!!
15:02:28 <felixfontein> https://en.wikipedia.org/wiki/AsciiDoc
15:02:33 <samccann> who knew we all had weep-lists
15:02:40 <bcoca> which is diff from ascii-docs
15:02:49 <acozine> all right, I think a poll is in order
15:02:58 <samccann> a VOTE!!!!
15:03:02 <samccann> who doesn't luv a vote
15:03:08 <felixfontein> didn't you have enough voting in the US recently?
15:03:27 * acozine looks at crossed-out items on 'things to cry about' list
15:03:27 <bcoca> felixfontein: ... too many jokes ... too many of them make me sad
15:03:32 <samccann> heh
15:03:47 <felixfontein> bcoca: sorry
15:03:56 <samccann> meanwhile... can we state what the naming convention should be?
15:04:11 <acozine> please vote +1 or -1 on "let's have two packages for documentation, and call them `ansible-docs-html` and `ansible-docs-rst`"
15:04:11 <samccann> is it `ansible-docs-<format>-doc`?
15:04:54 <acozine> uh-oh, did I do the poll thing correctly? I should have left it to our polling expert
15:04:56 <samccann> before we vote... can i ask why we can have one package with everything?
15:05:15 <felixfontein> samccann: because it's less packages to worry about
15:05:23 <samccann> rst, html,pdf,asciidoc,bcoca's grocery list ?
15:05:30 <bcoca> epub
15:05:33 <samccann> that's my point tho - just one BIG package
15:05:40 <samccann> that has everything docs related in it.
15:05:40 <acozine> samccann: because then it would be called `ansible-docs` and that would be confused with `ansible-doc` the command
15:05:48 <bcoca> i would make one tarball and let distros package either as single or multiple
15:05:53 <bcoca> ansilbe-docsite
15:05:53 <felixfontein> ansible-docs-all-docs
15:05:54 <samccann> call it ansible-rtfm for all I care
15:05:55 <felixfontein> :P
15:05:58 <acozine> heh
15:05:59 <acozine> okay
15:06:02 <bcoca> rtfm++
15:06:28 <felixfontein> I have no idea how large the docs in different formats will be
15:06:34 <samccann> then if we do get pdf and epub working, we just ram it in the same package. one package to RULE THEM ALL!
15:06:38 <acozine> heh
15:06:44 <samccann> does package size matter in this regard?
15:06:58 <samccann> it's an optional package
15:07:11 <acozine> well, one of the reasons we're moving the docs out of the main tarball is to speed downloads
15:07:14 <felixfontein> depends on how big it is compared to a pure-html or pure-rst package
15:07:21 <samccann> yes but the ansible download is 'important'
15:07:25 <acozine> heh, true
15:07:31 <samccann> the docs download is for the few who care/want it offline
15:08:08 <samccann> my nickel - let it get as big as it wants/needs and see if anyone opens an issue asking for us to slice n dice it into smaller packages
15:08:14 <samccann> (the docs package that is)
15:08:44 <samccann> unless someone here already knows of problems witha large docs package we should consider?
15:08:49 <felixfontein> yep. also system packagers can split it up if they think it's better that way
15:09:03 <acozine> works for me
15:09:08 <acozine> then what are we going to call it?
15:09:31 <felixfontein> ansible-rtfm, ansible-all-docs, ...?
15:09:42 <samccann> :-)
15:09:46 <tadeboro> I am pretty sure no end user will download the docs package. Distro package maintainers are the only exception here.
15:10:02 <tadeboro> What about ansible-documentation?
15:10:08 <bcoca> or we just package the rst's with instructions on how to create each format, let distro packagers choose
15:10:28 <bcoca> make pdf/html/asciicinema
15:10:46 <samccann> bcoca the reason we were thinking of adding html was to solve that repeat request we get for offline ansible docs. We figured it  would be easy to slot that one into the package
15:10:59 <acozine> yes, for airgapped environments
15:11:15 <samccann> ansible-bunker-docs :-)
15:11:18 <acozine> heh
15:11:18 <felixfontein> also if we include .html, we at least have a build process to point to which can be adjusted for other formats
15:11:33 <bcoca> samccann: that is why rst were included in main tarball, we used to have downstream packagers generate htmls and the afformentioned 'ansible-docs' packages
15:11:52 <acozine> tadeboro: I like ansible-documentation - it's clear
15:11:53 <samccann> interesting... good to know
15:12:08 <samccann> #info rst were included in main tarball, we used to have downstream packagers generate htmls and the afformentioned 'ansible-docs' packages
15:12:16 <bcoca> fyi, once generated, you can supply it many ways
15:12:35 <bcoca> ansible-documentation-all / ansible-documentation-html|rst|pdf ...
15:12:36 <acozine> I know rtfm is "edgy" but I dislike the attitude it projects
15:12:55 <samccann> yeah it's a fun name to think about but probably not a keeper
15:13:02 <felixfontein> +1 for 'documentation'
15:13:22 <samccann> as in `ansible-documentation`?
15:13:24 <felixfontein> ansible-core-documentation and ansible-documentation
15:13:27 <felixfontein> yes
15:13:30 <samccann> +1
15:13:43 <acozine> +1
15:13:45 <acozine> #chair
15:13:45 <zodbot> Current chairs: acozine dericcrago dmsimard felixfontein gundalow lmodemal samccann tadeboro
15:13:48 <bcoca> +1
15:13:49 <tadeboro> +1
15:13:55 <acozine> #chair bcoca
15:13:55 <zodbot> Current chairs: acozine bcoca dericcrago dmsimard felixfontein gundalow lmodemal samccann tadeboro
15:14:12 <felixfontein> +1
15:14:16 <lmodemal> +1
15:14:28 <bcoca> ansilbe-replicatedthefinemanual
15:14:53 <samccann> lol
15:15:26 <samccann> sounds like we have a winner on the naming and the split (one for base one for ansible)
15:16:21 <acozine> #agreed we'll build an `ansible-documentation` package so the documentation is available to those who want it but the main `ansible` package stays slim; when the time comes we'll build an `ansible-core-documentation` package also
15:16:45 <acozine> okay, what's our next step?
15:16:59 <samccann> beg someone to give it a try?
15:17:07 <samccann> how hard/easy is it to create a package?
15:17:34 <felixfontein> I might try it eventually, but not in the next 1-2 weeks I guess, too many other projects :)
15:17:54 <acozine> we'll have to modify the build process, right? so the docs don't go into the main package and they do go into a separate package
15:17:59 <samccann> if it's relatively easy, I'm up for trying, but I know ZERO about package creation/maintenance
15:18:17 <felixfontein> yes, but that's something we should only do once the documentation build process is working and tested
15:18:36 <felixfontein> i.e. first step would be to build the documentation package, get it published with new releases, and only then kick out docs from the existing package
15:18:36 <samccann> yeah... we'll need a certain badger's help for sure... and others
15:19:02 <samccann> ooo I like that.  are we agreed ^^^ seems like a good candidate for an info
15:19:03 <acozine> I think we can gather requirements before next week's meeting
15:19:48 <felixfontein> #info first step would be to build the documentation package, get it published with new releases, and only then kick out docs from the existing package
15:19:53 <samccann> :-) thanks
15:19:54 <felixfontein> like this?
15:19:58 <felixfontein> ok
15:20:17 <samccann> yeah I seldom go back to logs, but I do go back to meeting minutes to refresh my memory on what we all talked about etc
15:21:29 <samccann> we have a couple of agenda items from felixfontein.. should we move to them next?
15:21:32 <acozine> it can be really hard to read the full logs
15:21:38 <acozine> samccann: sounds good
15:21:47 <felixfontein> #topic sphinx extension
15:21:49 <felixfontein> quick update:
15:22:01 <felixfontein> #info there's a PR in the antsibull repository for the sphinx plugin: https://github.com/ansible-community/antsibull/pull/210
15:22:34 <felixfontein> #topic extending collection docs
15:22:41 <felixfontein> #topic extending collection docs (https://github.com/ansible/community/issues/521#issuecomment-723579328)
15:22:45 <felixfontein> this is a more interesting one :)
15:22:50 * samccann munches breakfast popcorm
15:22:53 <samccann> yes it is!
15:23:18 <felixfontein> right now, it is not possible to document test and filter plugins and roles
15:23:32 <samccann> I would love to move scenario etc guides over to their respective collections... where there is a one-one mapping
15:23:38 <felixfontein> well, at least not that they show up in the collection docs, like https://docs.ansible.com/ansible/latest/collections/community/general/
15:23:46 <samccann> hmm... the network team is doing just that
15:23:52 <samccann> lemme dig it up in the background
15:23:55 <felixfontein> yep, these should not be in ansible-base as well :)
15:24:13 <tadeboro> Technically, one can place markdown files into docs folder and Automation Hub (probably also galaxy-ng) will render them.
15:24:23 <acozine> yes, we can make much better use of documentation within collections
15:24:24 <felixfontein> the problem is that right now, you have to document roles, filters, test plugins, $random_other_stuff manually, and it won't show up on the docsite
15:24:43 <tadeboro> But markdown is really awkward to use for things that you want to interlink, index, etc.
15:25:02 <felixfontein> you can have many README.xxxx.md files, something in docs/, ..., but all that is only visible when people look at the repo (or click on links from the README)
15:25:10 <samccann> felixfontein - this is the collection that now has docs in test/filter plugins - https://github.com/ansible-collections/ansible.utils
15:25:20 <acozine> markdown is easier to write for many people, but rst is easier to integrate with existing content
15:25:46 <samccann> Given what they are doing (when you get a chance felixfontein to look) - do you think it will be a problem to have that come into the docsite via antsibull ?
15:25:50 <felixfontein> samccann: even if it would be included in ansible 2.10, these docs would be invisible on the docsite
15:26:17 <samccann> ah so that is a problem for sure. is it an antsibull enhancement needed?
15:26:27 <samccann> felixfontein ^^
15:26:51 <felixfontein> yes, it's needed, but first it should be decided on how it works
15:27:16 <felixfontein> also in the case of ansible.util, they use something that is similar to module/plugin docs, but not officially defined by ansible-base, like https://github.com/ansible-collections/ansible.utils/blob/main/plugins/test/validate.py
15:28:02 <acozine> they have .rst files in the `docs/` folder
15:28:03 <acozine> https://github.com/ansible-collections/ansible.utils/tree/main/docs
15:28:21 <felixfontein> I have no idea how these are generated, they are not generated by antsibull-docs
15:28:25 <samccann> #action samccann to followup on docs problems with ansible.utils - hey use something that is similar to module/plugin docs, but not officially defined by ansible-base, like https://github.com/ansible-collections/ansible.utils/blob/main/plugins/test/validate.py
15:28:35 <acozine> is that the same content that's in the plugin code?
15:28:46 <felixfontein> it looks similar
15:29:01 <samccann> felixfontein - they have their own script in collection_prep repo that generates rst files so they can link to them in their readme and have 'something' for galaxy users to read
15:29:08 <felixfontein> the problem is that it doesn't work well for existing filter/test plugins, since they can contain multiple different plugins in one file
15:29:44 <samccann> #info existing filter/test plugins can contain multiple different plugins in one file .. so the ansible.utils approach won't help
15:30:01 <felixfontein> at least not without modification :)
15:30:12 <acozine> hmm
15:30:13 <samccann> so it seems there are multiple problems
15:30:14 <felixfontein> also I think bcoca had a branch somewhere that allowed to document test/filter plugins, but no idea about details
15:30:24 <felixfontein> and then there are roles, which are probably not covered by ansible.utils either
15:31:05 <samccann> 1 - ansible.utils won't show up well on docsite
15:31:06 <samccann> 2. existing filters/test plugins remain undocumentable
15:31:06 <samccann> 3. people are putting multiple docs TYPES in collection /docs folder (md, rst) today
15:31:39 <samccann> 4. roles aren't documentable today either in the sense of antsibull pulling them into the docsite etc
15:31:45 <tadeboro> Maybe the role-argspec stuff will help when it comes to documenting roles? AT least variable types and descriptions will be there.
15:32:09 <felixfontein> tadeboro: I hope so, but it is hard to say without seeing how it looks like :)
15:32:56 <bcoca> felixfontein: wip
15:33:07 <bcoca> i should probably get it done before EoY
15:33:24 <felixfontein> bcoca: how does it look like? and does it also work for roles?
15:33:36 <bcoca> works for plugins, no matter where they live
15:33:37 <felixfontein> (might have asked that before, but forgot... sorry... and I guess the others don't know either)
15:33:45 <felixfontein> are roles plugins? :)
15:33:58 <bcoca> filters and tests
15:34:02 <bcoca> roles are not plugins
15:34:22 <bcoca> pr is to allow docs in filters and tests, the role spec project deasl with 'documenting roles'
15:34:24 <bcoca> and more
15:34:33 <acozine> bcoca: link?
15:34:38 <tadeboro> IIRC, argspec for roles looks quite like module argspec.
15:35:03 <bcoca> acozine: i'll look for later, multimeeting now
15:35:13 <tadeboro> With some added things like description (but I am not 100% sure about that one).
15:35:37 <bcoca> tadeboro: should lvrg same code, but wont be argspec
15:36:31 <tadeboro> I am thinking on a higher level: is there enough information there that we can generate a decent docs out of it. Implementation can be whatever.
15:36:32 <samccann> #action bcoca to post link to his WIP PR for docs in any plugin type (filters/tests etc)
15:36:57 <samccann> Does anyone have a pointer to the roles argspec that y'all are talking about?
15:37:24 <bcoca> several PRs
15:37:32 <bcoca> look for shrews as author
15:37:46 <samccann> for the roles argspec stuff bcoca?
15:37:46 <acozine> quick search turned up https://github.com/ansible/ansible/pull/44983 and https://github.com/ansible/ansible/pull/72120
15:37:53 <bcoca> y
15:37:55 <acozine> I think 72120 is the one bcoca is thinking of
15:38:02 <tadeboro> Is contributor summit video that demos the argspec available somewhere?
15:38:10 <bcoca> the old one was prev attempt, but same proj
15:38:20 <felixfontein> tadeboro: I think we also need to allow more docs, like scenario guides, but also which allow to document roles in more detail. for a complex role, you cannot squeeze all details into the format of a current plugin/module docs, without it becoming a mess
15:38:38 <samccann> #info roles argspec is wip. see https://github.com/ansible/ansible/pull/72120  ... might be more prs
15:38:41 <acozine> gundalow: do we ahve recordings of the contrib summit?
15:38:54 <acozine> (see tadeboro question above)
15:38:56 <gundalow> yes, let me find the link
15:39:08 <gundalow> https://www.youtube.com/ansible-community
15:39:10 <samccann> felixfontein - that's what leads me to the problem of what docs formats live in the /docs folder
15:39:23 <tadeboro> We write scenario docs for our collections in plain rst and just stick it inside the docs/source/somewhere.
15:39:29 <samccann> we (aka docs.ansible.com) want rst... but Automation Hub wants .md..
15:39:56 <samccann> (and I'm guessing galaxy-ng would be the same)
15:40:14 <tadeboro> AH ignores anything that is not markdown file, so having additional files is not a problem.
15:40:19 <gundalow> I've no idea if AH or galaxy-ng might support RST in the future
15:40:59 <tadeboro> Last time I talked to Red Hat people about Ansible + docs, I was informed that rst is too hard for collection devs and that markdown it is.
15:41:19 <samccann> the galaxy-ng docs format becomes a problem when we try to have all docs visible 'somewhere'?  As in those using .md now will be frustrated if we pull .rst into docs.ansible.com but not what they wrote in .md for example
15:41:20 <felixfontein> now I'm crying...
15:41:54 <samccann> my info on why it's md is well over a year old, but was based on the coding issues, not the authors finding rst too hard
15:41:54 <felixfontein> samccann: I guess conversion from .md to .rst can be easily done automatically
15:42:17 <acozine> samccann: agreed, i haven't heard from any actual developers complaining about using rst
15:42:30 <acozine> tadeboro: that makes me sad
15:42:46 <tadeboro> For our certified collections, we just have a placeholder markdown files in the repo that contain links to our documentation sites.
15:43:13 <tadeboro> https://github.com/sensu/sensu-go-ansible/blob/master/roles/install/README.md for example.
15:43:50 <samccann> so to attempt a summary - we have collection authors wanting to put more docs in collection /docs folders... wanting that to be visible in some instances on docs.ansible.com... in other instances in AH... and sometimes it's just pointers off to their own docsites
15:43:53 <felixfontein> simply including all .rst files from docs/ into the docsite is also not a good idea, since right now many collections have .rst files for all their plugins (f.ex. https://github.com/ansible-collections/amazon.aws/tree/main/docs) which we already have, so we don't want to duplicate that
15:43:53 <tadeboro> This way, AH users have easy access to docs and we do not have to maintain n different docs copies.
15:43:57 * gundalow isn't going to be rewriting RST as MD
15:44:23 <gundalow> I've not heard any real comments about RST being difficult
15:44:31 <felixfontein> gundalow: maybe there's a conversion tool. I'm not sure the result will look good, though
15:44:33 <acozine> tadeboro: that's a clean approach
15:45:20 <tadeboro> rst -> md sucks because there are things that you cannot do with md that rst+sphinx can do.
15:45:40 <acozine> the other way isn't great either
15:45:45 <acozine> md -> rst
15:45:47 <tadeboro> And I really like pandoc, but the end result is almost always bad.
15:45:48 <samccann> omgosh just say no to rst > md.  md > rst might be oka
15:46:04 <gundalow> felixfontein: I mean I'd want to hear some really good reasons why we need to move from MD to RST
15:46:14 <acozine> okay, we're 15 minutes over the official hour
15:46:19 <felixfontein> gundalow: do you mean RST to MD, or MD to RST?
15:46:21 <acozine> gundalow: I think you meant the other way around
15:46:29 <gundalow> woops, yes
15:46:31 <acozine> heh
15:46:49 <gundalow> I'd prefer to see AH/Galaxy_ng support RST
15:47:06 <acozine> me too
15:47:13 <felixfontein> me too
15:47:31 <tadeboro> Red Hat not so much unfortunately.
15:47:43 <tadeboro> BTW, https://github.com/sensu/sensu-go-ansible/blob/master/docs/Makefile.custom is how we render our docs.
15:47:43 <felixfontein> are they rendering .md as .html in javascript btw, or server-side?
15:48:19 <samccann> felixfontein  - alas i don't know. I do know it is a very limited subset of .md that is supported in AH.
15:49:43 <tadeboro> We basically just extract docs from the modules and place them into a designated source folder before running Sphinx.
15:49:46 <samccann> ok 20 min over.. how should we wrap this topic up?
15:50:07 <felixfontein> samccann: I guess 'think about it, needs more discussion and thinking' :)
15:50:17 <samccann> heh.
15:50:34 <acozine> maybe we could define a set of questions for next week?
15:50:38 <samccann> #info - there are competing needs/wants from a collection /docs folder.
15:50:48 <samccann> that would be good, yeah
15:51:22 <felixfontein> also it would probably help to involve all that are currently working on docs of some kind - galaxy, ansible.util, roles argspec, bcoca's branch, antsibull-docs, ...
15:51:31 <samccann> decide on the questions, then info each of them.. then action that we will reach out to The Powers That Be where needed for some details
15:52:08 <samccann> #info it would probably help to involve all that are currently working on docs of some kind - galaxy, ansible.util, roles argspec, bcoca's branch, antsibull-docs
15:52:20 <felixfontein> hope I didn't forget anyone :)
15:52:40 <felixfontein> maybe I should have added tadeboro to the list ;)
15:53:16 <samccann> so for me, the top question would be - who/what will consume the files within a collection /docs folder?  AH/galaxy-ng? docs.ansible.com in the future? ...gasp...access.redhat.com?
15:53:53 <samccann> if everything has to be repeated on AH AND docs.redhat.com.. we have problems.
15:53:56 <acozine> my favorite answer would be "all of the above"
15:54:02 <acozine> but that may not be practical
15:54:17 <felixfontein> "all of the above in one unified way" would be the best answer :)
15:54:24 <felixfontein> but yeah, probably not so practical
15:54:41 <samccann> so we agree that's one of the questions?
15:54:50 <felixfontein> I think so
15:54:53 <tadeboro> +1
15:55:00 <samccann> #info who/what will consume the files within a collection /docs folder?  AH/galaxy-ng? docs.ansible.com in the future? ...gasp...access.redhat.com?
15:55:06 <acozine> heh
15:55:08 <felixfontein> btw, galaxy (non -ng) delivers the README rendered as HTML to the client
15:55:29 <acozine> yes, and that's markdown, right?
15:55:42 <felixfontein> yes, but at least it's rendered server-side
15:55:48 <felixfontein> no idea about galaxy-ng though
15:55:57 <acozine> it's also possible to render rst as HTML the way GitHub does . . . it's not great but it's better than nothing
15:55:57 <felixfontein> I have no access to AH, so I don't think I can see it in action
15:56:18 * tadeboro logs into AH to check ... just a sec
15:56:22 <felixfontein> acozine: it's definitely possible, but you don't want to have to do it in the client with JavaScript
15:56:25 <samccann> my next question would be - what is the timeline for getting filter/test plugins documentable
15:56:47 <felixfontein> it would be good to see how bcoca's solution looks like, and compare it with the ansible.utils solution
15:57:24 <samccann> yeah. ansible.utils releases dec 1.  So I'm thinking that means it shows up in Ansible 2.11 ? or can a new collection be added to 2.10?
15:57:28 <felixfontein> also I think that a solution would also involve ansible-doc
15:57:54 <felixfontein> right now we haven't really decided if anything can be added to 2.10 that's not already part of 2.10 (i.e. content moved to new collections)
15:58:18 <samccann> #info - what's the timeline for getting fitler/test plugins documentable and working with `ansible-doc` and how does this relate to wha `ansible.utils` is doing in their Dec release?
15:58:24 <felixfontein> at least ansible.utils is not really needed to document test/filter plugins, it only shows how it could be done
15:58:43 <felixfontein> proper support is needed in ansible-doc and antsibull
15:58:49 <samccann> yeah I need to let that team know their docs won't show up on docs.ansible.com for now (for the test/filter joy)
15:59:19 <felixfontein> like all test/filter docs that aren't included in the regular ansible-base docsite
15:59:35 <samccann> antsibull could bring it in say by 2.11, but I wonder/worry about bcoca's work in `ansible-base` to make this work for other stuff... and would that be in ansible-base 2.10.x or not til 2.11 etc
15:59:47 <bcoca> felixfontein: the plan is adding them to ansible-doc so they can be included
16:00:17 <bcoca> iirc, ansible.utils is mostly a copy of my early work in this matter, except the ignored the diff 'common plugin fields'
16:00:34 <felixfontein> bcoca: part of the problem is that it will take a long time until ansible actually uses ansible-base 2.11, so if that isn't backported, antsibull might need to do some magic to make it work earlier
16:01:06 <felixfontein> bcoca: ah, so it will look similar to what ansible.utils in the plugins?
16:01:12 <bcoca> well, we have been very lenient on what we backport till 2.9, specially if it helps collections
16:01:22 <samccann> #info what is the timeline for the roles argspec and does it solve all the roles documentation needs, or will roles also want manually written docs within a collection /docs folder (and thus need subfolders which aren't supported today?
16:01:31 <felixfontein> bcoca: like collection routing? ;)
16:01:39 <bcoca> felixfontein: iirc, last time i look it was ast parsing and then taking the docstring, whcih was my initial implementation
16:01:57 <felixfontein> samccann: I'm pretty sure that (at least some) docs also need manual written docs in addition
16:02:19 <samccann> #info can we also support other manual docs, like scenario guides in the collection /docs folder etc?
16:02:27 <felixfontein> bcoca: so does your solution also require one plugin per .py file?
16:02:34 <bcoca> no
16:02:34 <samccann> anything else we need before we colse the meeting? we are 1.5 hrs along now
16:02:45 <tadeboro> AH send JSON over to the forntend and then renders that.
16:02:56 <tadeboro> felixfontein: ^
16:02:59 <felixfontein> tadeboro: does the JSON contain the README as .md or .html?
16:03:09 <felixfontein> for galaxy (without -ng), it's .html inside the JSON
16:03:55 <felixfontein> samccann: I guess we should close it, otherwise we'll just continue forever
16:04:26 <samccann> heh ok
16:04:28 <samccann> thanks everyone!
16:04:31 <samccann> #endmeeting