14:31:28 #startmeeting Documentation Working Group aka DaWGs 14:31:28 Meeting started Tue Nov 10 14:31:28 2020 UTC. 14:31:28 This meeting is logged and archived in a public location. 14:31:28 The chair is samccann. Information about MeetBot at http://wiki.debian.org/MeetBot. 14:31:28 Useful Commands: #action #agreed #halp #info #idea #link #topic. 14:31:28 The meeting name has been set to 'documentation_working_group_aka_dawgs' 14:31:36 o/ 14:31:50 oh thank the lord... I can't remember half the commands! 14:32:00 heh 14:32:07 #topic opening chatter 14:32:13 hmmm 14:32:53 apparently I can't either? or else freenode is having a bad day 14:33:05 #topic welcoming chatter 14:33:08 nope 14:33:18 oh, well 14:33:21 * gundalow waves 14:33:23 o/ 14:33:27 freeform meeting i guess ;-) 14:33:27 soe #chair are needed 14:33:28 hi 14:33:38 heh 14:33:43 I can't chair until I am a chair 14:33:51 #chair acozine 14:33:51 Current chairs: acozine samccann 14:33:56 thanks! 14:34:00 sorry about that! rough start ;-) 14:34:05 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 #chair dericcrago gundalow felixfontein dmsimard lmodemal 14:34:22 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 #topic opening chatter 14:35:02 there we go - thanks felixfontein 14:35:13 (for the pointer) 14:35:48 brb restarting router 14:35:53 resp. modem 14:36:16 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 I am here but have not yet looked at the agenda for today. 14:37:07 tremble: cool, do you want to be a chair? 14:37:13 #chair tadeboro 14:37:13 Current chairs: acozine dericcrago dmsimard felixfontein gundalow lmodemal samccann tadeboro 14:37:14 nah 14:37:21 * acozine nods 14:37:35 tadeboro: neither have I . . . we'll all look together 14:38:35 #info agenda https://github.com/ansible/community/issues/521#issuecomment-721211831 14:39:07 plus following comments 14:39:41 yep 14:40:03 re 14:40:05 #topic version split and supplementary meeting 14:40:25 quick summary: 14:40:59 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 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 is the new name ansible-core final now 14:42:01 ? 14:42:10 felixfontein: ah, no 14:42:16 ok :) 14:42:18 sorry to interrupt 14:42:24 at least, not so far as I know . . . 14:42:47 anyway, soon we will have two different things with the same version number 14:43:35 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 that meeting is on Thursdays 14:44:05 #info Thurs supplemental meeting minutes from last week - https://github.com/ansible/community/issues/521#issuecomment-721211489 14:44:06 it starts at UTC one hour later than this current meeting 14:44:07 I hate so suggest it but should the *name* of one of the 'Ansible's change to something completely different... 14:44:35 Not your call, but it's really going to get painful. 14:44:40 tremble: that is a possible solution, or part of one 14:44:51 #info weekly Thurs supplemental meeting starts 10:30am ET on #ansible-docs to cover splitting the docsite 14:45:37 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 I second tremble. but that's nothing this meeting can decide I guess :) 14:46:13 let's say we announce that the code formerly known as ansible-core will now be known as fumblefluff 14:46:14 #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 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 a new name would help with public understanding 14:47:31 but it doesn't solve all the documentation challenges 14:47:36 We should probably leave that to Thursday's meeting or it will fumblefluff its way through the entire hour here :-) 14:48:09 samccann: true . . . 14:48:47 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 bring your friends 14:48:53 all are welcome! 14:49:15 #topic removing docs files from Ansible tarballs 14:49:53 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 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 I think so 14:50:25 do we also want an ansible-base-docs tarball next to the ansible-base tarball? 14:50:35 probably 14:50:44 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 I think the more we set a pattern and stick to it everywhere, the less confusing this will be 14:51:18 ^^^ was in response to felixfontein 14:51:32 fumblefluff-docs FTW~~~ 14:51:32 ansible-manual 14:51:43 or ansible-documentation 14:51:58 for system packages, the naming schema *, *-docs, *-src is pretty common I think 14:52:00 ansible-rtfm 14:52:01 ansible-rtfm 14:52:06 jinx! 14:52:08 hahah JINX! 14:52:10 heh 14:52:13 dagnammit! 14:52:43 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 what should the tarballs contain? just the .rst files? also .html files? or even more formats? 14:53:38 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 bcoca: what kind of confusion? 14:54:09 felixfontein: the -docsrc for rst the others we can do by format ansible-dochtml ? 14:54:10 bcoca: did people assume that `ansible-doc` (tool) is contained in `ansible-docs` (package)? 14:54:20 acozine: peopel refering to the package thinkging it provided the cli 14:54:26 felixfontein: exactly 14:54:43 meh. people are always good at ignoring missing/extra letters. 14:55:17 So I think we can avoid the tool confusion by giving it another name. 14:55:31 We could even use `ansible-html` and include the rst files inside it 14:55:38 felixfontein: people just as easily plurialize the singular by mistake 14:56:07 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 hmm, how about `ansible-docs-html` - otherwise it's not clear what the content is 14:56:29 ansible-html-docs 14:56:34 ansible-docs-rst, ansible-docs-html, ...? 14:56:36 or ^^^ 14:56:43 yeah, I like that 14:56:58 the docs end matches the convention, adding type in the middle will ensure users READ that part 14:56:59 though it does ruin autocomplete 14:57:12 just for package install .. im fine with that 14:57:20 I prefer -docs- so that if you sort alphabetically, they are grouped if other ansible-* packages are around 14:57:21 since it wont create actual binaries in shell 14:57:41 felixfontein: but as you mentioned, that would violate many distro naming conventions 14:57:49 though i've seen it both ways 14:57:50 #info need to be careful on naming the docs package so no one confuses it with `ansible-docs` the cli command. 14:58:15 s/ansible-docs/ansible-doc/ ;) 14:58:19 so there is a sort of convention of docs packages being named fumblefluff-docs ? 14:58:37 what are the odds that packagers will rename them `ansible-docs-html-docs` and `ansible-docs-rst-docs`? 14:58:44 #uninfo 14:58:48 #undo 14:58:48 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 acozine: high ... 14:58:54 sadly 14:59:00 heh 14:59:03 I was joking 14:59:08 but actually I'd be fine with that 14:59:09 #info need to be careful on naming the docs package so no one confuses it with `ansible-doc` the cli command 14:59:33 I think I prefer ansible-docs-html-docs over ansible-html-docs 14:59:39 me too 14:59:52 * bcoca adds note to 'things to cry about' list 14:59:58 awww 15:00:03 * acozine passes tissues to bcoca 15:00:07 i'm missing the need for the docs in the middle? 15:00:09 lol 15:00:23 to me, it starts once again to confuse it with `ansible-doc` command 15:00:24 samccann: its a sorting issue when listing packages 15:00:26 samccann: grouping when package names are sorted alphabetically 15:00:42 ah ok 15:00:46 but i think that better name > sorting issue, just mho 15:00:49 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 then ansible-core isn't between ansible-ascii-docs and ansible-html-docs ;) 15:01:23 felixfontein: ascii-docs are included in core! 15:01:45 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 you mean asciidoc-docs 15:02:21 LOL!!! 15:02:28 https://en.wikipedia.org/wiki/AsciiDoc 15:02:33 who knew we all had weep-lists 15:02:40 which is diff from ascii-docs 15:02:49 all right, I think a poll is in order 15:02:58 a VOTE!!!! 15:03:02 who doesn't luv a vote 15:03:08 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 felixfontein: ... too many jokes ... too many of them make me sad 15:03:32 heh 15:03:47 bcoca: sorry 15:03:56 meanwhile... can we state what the naming convention should be? 15:04:11 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 is it `ansible-docs--doc`? 15:04:54 uh-oh, did I do the poll thing correctly? I should have left it to our polling expert 15:04:56 before we vote... can i ask why we can have one package with everything? 15:05:15 samccann: because it's less packages to worry about 15:05:23 rst, html,pdf,asciidoc,bcoca's grocery list ? 15:05:30 epub 15:05:33 that's my point tho - just one BIG package 15:05:40 that has everything docs related in it. 15:05:40 samccann: because then it would be called `ansible-docs` and that would be confused with `ansible-doc` the command 15:05:48 i would make one tarball and let distros package either as single or multiple 15:05:53 ansilbe-docsite 15:05:53 ansible-docs-all-docs 15:05:54 call it ansible-rtfm for all I care 15:05:55 :P 15:05:58 heh 15:05:59 okay 15:06:02 rtfm++ 15:06:28 I have no idea how large the docs in different formats will be 15:06:34 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 heh 15:06:44 does package size matter in this regard? 15:06:58 it's an optional package 15:07:11 well, one of the reasons we're moving the docs out of the main tarball is to speed downloads 15:07:14 depends on how big it is compared to a pure-html or pure-rst package 15:07:21 yes but the ansible download is 'important' 15:07:25 heh, true 15:07:31 the docs download is for the few who care/want it offline 15:08:08 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 (the docs package that is) 15:08:44 unless someone here already knows of problems witha large docs package we should consider? 15:08:49 yep. also system packagers can split it up if they think it's better that way 15:09:03 works for me 15:09:08 then what are we going to call it? 15:09:31 ansible-rtfm, ansible-all-docs, ...? 15:09:42 :-) 15:09:46 I am pretty sure no end user will download the docs package. Distro package maintainers are the only exception here. 15:10:02 What about ansible-documentation? 15:10:08 or we just package the rst's with instructions on how to create each format, let distro packagers choose 15:10:28 make pdf/html/asciicinema 15:10:46 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 yes, for airgapped environments 15:11:15 ansible-bunker-docs :-) 15:11:18 heh 15:11:18 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 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 tadeboro: I like ansible-documentation - it's clear 15:11:53 interesting... good to know 15:12:08 #info rst were included in main tarball, we used to have downstream packagers generate htmls and the afformentioned 'ansible-docs' packages 15:12:16 fyi, once generated, you can supply it many ways 15:12:35 ansible-documentation-all / ansible-documentation-html|rst|pdf ... 15:12:36 I know rtfm is "edgy" but I dislike the attitude it projects 15:12:55 yeah it's a fun name to think about but probably not a keeper 15:13:02 +1 for 'documentation' 15:13:22 as in `ansible-documentation`? 15:13:24 ansible-core-documentation and ansible-documentation 15:13:27 yes 15:13:30 +1 15:13:43 +1 15:13:45 #chair 15:13:45 Current chairs: acozine dericcrago dmsimard felixfontein gundalow lmodemal samccann tadeboro 15:13:48 +1 15:13:49 +1 15:13:55 #chair bcoca 15:13:55 Current chairs: acozine bcoca dericcrago dmsimard felixfontein gundalow lmodemal samccann tadeboro 15:14:12 +1 15:14:16 +1 15:14:28 ansilbe-replicatedthefinemanual 15:14:53 lol 15:15:26 sounds like we have a winner on the naming and the split (one for base one for ansible) 15:16:21 #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 okay, what's our next step? 15:16:59 beg someone to give it a try? 15:17:07 how hard/easy is it to create a package? 15:17:34 I might try it eventually, but not in the next 1-2 weeks I guess, too many other projects :) 15:17:54 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 if it's relatively easy, I'm up for trying, but I know ZERO about package creation/maintenance 15:18:17 yes, but that's something we should only do once the documentation build process is working and tested 15:18:36 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 yeah... we'll need a certain badger's help for sure... and others 15:19:02 ooo I like that. are we agreed ^^^ seems like a good candidate for an info 15:19:03 I think we can gather requirements before next week's meeting 15:19:48 #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 :-) thanks 15:19:54 like this? 15:19:58 ok 15:20:17 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 we have a couple of agenda items from felixfontein.. should we move to them next? 15:21:32 it can be really hard to read the full logs 15:21:38 samccann: sounds good 15:21:47 #topic sphinx extension 15:21:49 quick update: 15:22:01 #info there's a PR in the antsibull repository for the sphinx plugin: https://github.com/ansible-community/antsibull/pull/210 15:22:34 #topic extending collection docs 15:22:41 #topic extending collection docs (https://github.com/ansible/community/issues/521#issuecomment-723579328) 15:22:45 this is a more interesting one :) 15:22:50 * samccann munches breakfast popcorm 15:22:53 yes it is! 15:23:18 right now, it is not possible to document test and filter plugins and roles 15:23:32 I would love to move scenario etc guides over to their respective collections... where there is a one-one mapping 15:23:38 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 hmm... the network team is doing just that 15:23:52 lemme dig it up in the background 15:23:55 yep, these should not be in ansible-base as well :) 15:24:13 Technically, one can place markdown files into docs folder and Automation Hub (probably also galaxy-ng) will render them. 15:24:23 yes, we can make much better use of documentation within collections 15:24:24 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 But markdown is really awkward to use for things that you want to interlink, index, etc. 15:25:02 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 felixfontein - this is the collection that now has docs in test/filter plugins - https://github.com/ansible-collections/ansible.utils 15:25:20 markdown is easier to write for many people, but rst is easier to integrate with existing content 15:25:46 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 samccann: even if it would be included in ansible 2.10, these docs would be invisible on the docsite 15:26:17 ah so that is a problem for sure. is it an antsibull enhancement needed? 15:26:27 felixfontein ^^ 15:26:51 yes, it's needed, but first it should be decided on how it works 15:27:16 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 they have .rst files in the `docs/` folder 15:28:03 https://github.com/ansible-collections/ansible.utils/tree/main/docs 15:28:21 I have no idea how these are generated, they are not generated by antsibull-docs 15:28:25 #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 is that the same content that's in the plugin code? 15:28:46 it looks similar 15:29:01 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 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 #info existing filter/test plugins can contain multiple different plugins in one file .. so the ansible.utils approach won't help 15:30:01 at least not without modification :) 15:30:12 hmm 15:30:13 so it seems there are multiple problems 15:30:14 also I think bcoca had a branch somewhere that allowed to document test/filter plugins, but no idea about details 15:30:24 and then there are roles, which are probably not covered by ansible.utils either 15:31:05 1 - ansible.utils won't show up well on docsite 15:31:06 2. existing filters/test plugins remain undocumentable 15:31:06 3. people are putting multiple docs TYPES in collection /docs folder (md, rst) today 15:31:39 4. roles aren't documentable today either in the sense of antsibull pulling them into the docsite etc 15:31:45 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 tadeboro: I hope so, but it is hard to say without seeing how it looks like :) 15:32:56 felixfontein: wip 15:33:07 i should probably get it done before EoY 15:33:24 bcoca: how does it look like? and does it also work for roles? 15:33:36 works for plugins, no matter where they live 15:33:37 (might have asked that before, but forgot... sorry... and I guess the others don't know either) 15:33:45 are roles plugins? :) 15:33:58 filters and tests 15:34:02 roles are not plugins 15:34:22 pr is to allow docs in filters and tests, the role spec project deasl with 'documenting roles' 15:34:24 and more 15:34:33 bcoca: link? 15:34:38 IIRC, argspec for roles looks quite like module argspec. 15:35:03 acozine: i'll look for later, multimeeting now 15:35:13 With some added things like description (but I am not 100% sure about that one). 15:35:37 tadeboro: should lvrg same code, but wont be argspec 15:36:31 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 #action bcoca to post link to his WIP PR for docs in any plugin type (filters/tests etc) 15:36:57 Does anyone have a pointer to the roles argspec that y'all are talking about? 15:37:24 several PRs 15:37:32 look for shrews as author 15:37:46 for the roles argspec stuff bcoca? 15:37:46 quick search turned up https://github.com/ansible/ansible/pull/44983 and https://github.com/ansible/ansible/pull/72120 15:37:53 y 15:37:55 I think 72120 is the one bcoca is thinking of 15:38:02 Is contributor summit video that demos the argspec available somewhere? 15:38:10 the old one was prev attempt, but same proj 15:38:20 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 #info roles argspec is wip. see https://github.com/ansible/ansible/pull/72120 ... might be more prs 15:38:41 gundalow: do we ahve recordings of the contrib summit? 15:38:54 (see tadeboro question above) 15:38:56 yes, let me find the link 15:39:08 https://www.youtube.com/ansible-community 15:39:10 felixfontein - that's what leads me to the problem of what docs formats live in the /docs folder 15:39:23 We write scenario docs for our collections in plain rst and just stick it inside the docs/source/somewhere. 15:39:29 we (aka docs.ansible.com) want rst... but Automation Hub wants .md.. 15:39:56 (and I'm guessing galaxy-ng would be the same) 15:40:14 AH ignores anything that is not markdown file, so having additional files is not a problem. 15:40:19 I've no idea if AH or galaxy-ng might support RST in the future 15:40:59 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 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 now I'm crying... 15:41:54 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 samccann: I guess conversion from .md to .rst can be easily done automatically 15:42:17 samccann: agreed, i haven't heard from any actual developers complaining about using rst 15:42:30 tadeboro: that makes me sad 15:42:46 For our certified collections, we just have a placeholder markdown files in the repo that contain links to our documentation sites. 15:43:13 https://github.com/sensu/sensu-go-ansible/blob/master/roles/install/README.md for example. 15:43:50 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 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 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 I've not heard any real comments about RST being difficult 15:44:31 gundalow: maybe there's a conversion tool. I'm not sure the result will look good, though 15:44:33 tadeboro: that's a clean approach 15:45:20 rst -> md sucks because there are things that you cannot do with md that rst+sphinx can do. 15:45:40 the other way isn't great either 15:45:45 md -> rst 15:45:47 And I really like pandoc, but the end result is almost always bad. 15:45:48 omgosh just say no to rst > md. md > rst might be oka 15:46:04 felixfontein: I mean I'd want to hear some really good reasons why we need to move from MD to RST 15:46:14 okay, we're 15 minutes over the official hour 15:46:19 gundalow: do you mean RST to MD, or MD to RST? 15:46:21 gundalow: I think you meant the other way around 15:46:29 woops, yes 15:46:31 heh 15:46:49 I'd prefer to see AH/Galaxy_ng support RST 15:47:06 me too 15:47:13 me too 15:47:31 Red Hat not so much unfortunately. 15:47:43 BTW, https://github.com/sensu/sensu-go-ansible/blob/master/docs/Makefile.custom is how we render our docs. 15:47:43 are they rendering .md as .html in javascript btw, or server-side? 15:48:19 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 We basically just extract docs from the modules and place them into a designated source folder before running Sphinx. 15:49:46 ok 20 min over.. how should we wrap this topic up? 15:50:07 samccann: I guess 'think about it, needs more discussion and thinking' :) 15:50:17 heh. 15:50:34 maybe we could define a set of questions for next week? 15:50:38 #info - there are competing needs/wants from a collection /docs folder. 15:50:48 that would be good, yeah 15:51:22 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 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 #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 hope I didn't forget anyone :) 15:52:40 maybe I should have added tadeboro to the list ;) 15:53:16 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 if everything has to be repeated on AH AND docs.redhat.com.. we have problems. 15:53:56 my favorite answer would be "all of the above" 15:54:02 but that may not be practical 15:54:17 "all of the above in one unified way" would be the best answer :) 15:54:24 but yeah, probably not so practical 15:54:41 so we agree that's one of the questions? 15:54:50 I think so 15:54:53 +1 15:55:00 #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 heh 15:55:08 btw, galaxy (non -ng) delivers the README rendered as HTML to the client 15:55:29 yes, and that's markdown, right? 15:55:42 yes, but at least it's rendered server-side 15:55:48 no idea about galaxy-ng though 15:55:57 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 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 acozine: it's definitely possible, but you don't want to have to do it in the client with JavaScript 15:56:25 my next question would be - what is the timeline for getting filter/test plugins documentable 15:56:47 it would be good to see how bcoca's solution looks like, and compare it with the ansible.utils solution 15:57:24