14:31:04 #startmeeting Documentation Working Group aka DaWGs 14:31:04 Meeting started Tue Oct 20 14:31:04 2020 UTC. 14:31:04 This meeting is logged and archived in a public location. 14:31:04 The chair is acozine. Information about MeetBot at http://wiki.debian.org/MeetBot. 14:31:04 Useful Commands: #action #agreed #halp #info #idea #link #topic. 14:31:04 The meeting name has been set to 'documentation_working_group_aka_dawgs' 14:31:13 /me waves 14:31:16 #topic opening chatter 14:31:16 * gundalow waves 14:31:18 who's around? 14:31:22 #chair gundalow 14:31:22 Current chairs: acozine gundalow 14:31:24 Hello :) 14:31:29 #chair lmodemal 14:31:29 Current chairs: acozine gundalow lmodemal 14:31:34 hello, hello! 14:31:37 o/ 14:31:43 #chair samccann 14:31:43 Current chairs: acozine gundalow lmodemal samccann 14:33:06 usual suspects andersson007_ baptistemm briantist cyberpear felixfontein madonius persysted tadeboro tributarian zbr you folks talking docs today? 14:33:27 * zbr not me 14:33:45 im in 14:33:51 #chair tributarian 14:33:51 Current chairs: acozine gundalow lmodemal samccann tributarian 14:34:08 zbr: have a good 14:35:13 hi! 14:35:22 #chair felixfontein 14:35:22 Current chairs: acozine felixfontein gundalow lmodemal samccann tributarian 14:35:25 (I'm partially here) 14:35:28 heh 14:35:49 * acozine needs a "footstool" command for partial participation 14:36:17 felixfontein: do you want to be a chair? 14:36:33 * tadeboro is in the middle of the woods with kids, so he will skip today's meeting 14:36:37 we can take you off the list for today 14:36:44 tadeboro: sounds lovely, enjoy! 14:36:51 happy mushrooming 14:37:18 hm, looks like there's no official agenda today! 14:37:24 https://github.com/ansible/community/issues/521 is our agenda spot 14:37:43 I think between Fest and the Contributor Summit we got a bit distracted 14:38:18 yes there is 14:38:28 https://github.com/ansible/community/issues/521#issuecomment-704386942 14:38:50 sorry, the meeting notes from the contributor summit came after I created the agenda :-( 14:38:57 but today is 10/20 14:39:04 oh, of course 14:39:09 we didn't have a meeting last week 14:39:11 heh I'm date challenged. 14:39:14 heh 14:39:14 we did. 14:39:22 oh no we didn't doh! 14:39:32 but anyway, I'll update the date, but that's the agenda 14:39:36 excellent! 14:40:09 good :) 14:40:30 #topic clarifying RH supported version vs. latest community version 14:40:32 https://github.com/ansible/ansible/issues/72199 14:40:58 so we had a discussion when 2.10 came out about whether or not to update `latest` to point at 2.10 14:41:18 and we decided the answer was yes, we would point `latest` to 2.10 14:42:05 so RH supports only (up to) 2.9? 14:42:09 but there is no downstream (RHEL-packaged, RH-supported) 2.10, so folks with support contracts need the 2.9 docs 14:42:13 felixfontein: that's correct 14:42:32 do they plan to support ansible-base 2.10/2.11 eventually? 14:42:45 or do they want to stick with 2.9 for a longer time? 14:43:09 2.10 I think will only be a community release 14:43:21 or will there be a 'redhat ansible 2.10' which is ansible-base 2.10 + supported collections? 14:43:35 interesting 14:43:52 I think there will be a "Red Hat Ansible 2.11" which will be ansible-base 2.11 + supported collections 14:43:58 I'm personally not sure, but I got the feeling what comes next is execution environments, which would include a version of ansible-base... but that's reaaaal guesswork 14:44:31 hmm. ok :) let's see. sorry for interrupting :) 14:44:50 ah, okay, so ansible-base 2.11 in a container with selected supported collections, maybe 14:45:19 yeah just a real guess tho. nothing to base decisions off of :-) 14:45:24 I think it is a bit odd to have latest not point to latest 14:45:31 maybe 'stable' 14:45:46 that could be an option - to add a 'stable' 14:46:02 tributarian: yes, `latest` will stay on 2.10 14:46:06 although that implies latest is unstable 14:46:11 heh 14:46:12 I think bcoca suggested somthing similar - to have 2.9 use 'some alias' like we did with latest 14:46:34 if the dropdown allows it, I think it would be great to put a miniature Red Hat icon on the supported versions 14:46:51 also, we should change the banner on 2.9 14:46:53 my guess is no, it won't support an icon there. Maybe in the banner 14:47:26 but to keep on one track for now - do we want to consider an alias (whether it is stable or latest_supported) or something? 14:47:29 samccann: are we using a sphinx plug-in for the dropdown? 14:47:30 for 2.9? 14:47:51 samccann: yes, I think another alias is worth exploring 14:47:52 acozine: - no, it's hacked code from a sphinx PR that was rejected. 14:47:57 heh 14:47:59 classic 14:48:09 best I could do :-) 14:48:17 hey, working code wins 14:48:35 that said, if someone wants to make it work better, I'm all for it 14:50:03 icons in a can only be customized with CSS in a very, very limited way 14:50:44 thanks felixfontein 14:50:56 how about latest and latest-community 14:51:26 I'd prefer latest and latest-redhat :) 14:51:29 i'd opt for latest and latest-supported... but that suggest everything written in 2.9 is supported, and it isn't 14:51:32 so /latest/ stays 2.10 14:51:38 felixfontein: that works 14:51:42 ooo latest-redhat is good 14:51:55 dropdown code originally introduced here: https://github.com/ansible/ansible/pull/55655/files 14:52:55 yeah, I like `latest-redhat` 14:53:02 gundalow: what do you think of something like aliasing 2.9 to `latest-redhat` ? 14:53:14 do you have to ask marketing for that? 14:53:18 probably 14:54:02 my thought is - we come to some kind of warm fuzzy agreement here, then bring it to marketing and The Powers That Be to see if they agree 14:54:18 ok :) 14:54:43 hmmm 14:55:20 we might need a banner on latest too . . . because that's what google searches send people to 14:55:25 I like `latest-redhat` 14:55:28 but maybe I'm borrowing trouble there 14:55:42 you are correct, we do need to update the /latest/ banner 14:56:23 samccann: while we could do `latest-redhat` who would know to look there? 14:56:27 so we need 'something' to late people on /latest/ know it's the latest upstream release, and tell them to go to /latest-redhat/ in the dropdown if they are looking for redhat release 14:56:44 s/late/let 14:57:09 ah, gotcha 14:57:21 Alternately, we have a /latest/ banner to say it is upstream only, and a note to say 2.8 and 2.9 reflect Red Hat releases 14:57:53 and update 2.9 to remove the 'this is old stuff' banner and say something similar - this is the latest red hat release. if you are looking for the latest upstream release - select latest from the dropdown 14:58:23 so we could do it all w/o any alias 14:58:35 Are the banners per branch? 14:59:54 not yet, but they could be 15:00:07 we have latest, and not-latest, and eol today 15:00:23 a bit of code and we can have latest, rhel-latest, not-latest, and eol 15:00:39 ^^^ not the real coding names but just for illustration 15:01:06 my guess is I could get it working today if that's what we want 15:01:33 I think it's a step in the right direction 15:01:51 so if you can get it working today, I say go for it 15:02:37 Yup, that feels pragmatic 15:03:08 #action samccann to create separate banners to denote latest vs rh latest and test on jenkins 15:03:18 \o/ 15:03:35 #info we will update banners on latest/2.10 and 2.9 to distinguish what is upstream latest and what is downstream latest releases 15:03:47 * samccann forgot to info anything till now... doh 15:03:52 heh 15:04:27 let's follow up on that next week 15:04:42 I'm going to skip around on the agenda a bit 15:05:22 #topic removing docs source files from the Ansible tarball 15:05:25 https://github.com/ansible-collections/overview/discussions/120 15:05:40 is this about ansible-base, ansible, or both? 15:05:43 bit of background on that one 15:05:51 it's them and more! 15:06:19 So we know the Ansible package is kinda big... so last time we met, we talked a bit about removing the ansible/ansible .rst files from the package to help with the size 15:06:43 we also mentioned that collections include .rst files (some of them) and removing them would also reduce the Ansible package size 15:06:48 and then! 15:07:23 I noticed we had a proposal to remove the /test folder from collection tarballs, so I figured I'd add a proposal to remove the /docs folder from collection tarballs as well.. to see if that's a good idea or not 15:07:25 so it's the ansible/ansible .rst files for the ansible-base tarball, and the collection .rst files for the ansible tarball? 15:07:57 the Ansible package tarball also includes the ansible/ansible .rst files. So yes, we can consider removing basically all .rst files from everything 15:08:21 or pick and choose where it makes sense. I'm just unclear if anyone used/cared about those .rst files in any of the tarballs to begin with. 15:08:54 hmmm 15:09:18 the Ansible tarball does not, it's really the ansible-base tarball that does contain the ansible/ansible .rst files 15:09:25 * samccann always worries when acozine hmmms 15:09:40 ah my mistake 15:09:43 no problem :) 15:09:45 1) Are the collection RST files useful to anyone 15:09:45 2) Legal might say we can't remove them 15:09:45 3) People might be using the RST from ansible-base as that's existed a lot longer 15:10:04 we generate the modules-in-collections docs from the python files in the collection tarballs on Galaxy . . . so we create our own .rst files when we generate those . . . 15:10:16 #info are collection RST files useful to anyone? 15:10:25 #info Legal might say we cannot remove them 15:10:41 #info people might be using the RST from ansible-base since that's been around a lot longer 15:11:17 acozine - correct. It's the collection owners who are generating .rst files within their `/docs` folders since Galaxy isn't displaying module docs yet. It's a workaround 15:11:40 in the extracted ansible tarball, roughly 10% of the space is used by collection docs 15:11:41 but for ansible-base, there's the licensing issue, right? the distributed artifact must contain all the source code? 15:11:44 and also because docs.ansible.com is tied to a specific collection release that isn't the most recent, so they don't want to depend on that either 15:11:58 felixfontein: collection docs in .rst format? 15:12:02 wow, that's a lot 15:12:04 acozine: yep. 15:12:07 for the collections that generate their own RST files, is that so people can look in https://github.com/ansible-collections/ansible.utils/tree/main/docs to see the latest and greatest source (rather than d.a.c). So if we `build_ignore` those files they will still be in GitHub so people can view them 15:12:20 acozine: or whatever they have in their /docs folders :) 15:12:57 the folks I know of generating their own RST files - yes, they point to them all from their collection readme so a galaxy user can easily find them. 15:13:22 if the collection comes with a script which allows to re-create the .rst files, omitting them from the tarball uploaded to galaxy should be fine from a legal point of view. but IANAL. 15:13:46 but then it also seems like a similar thing - if they are in gitub, are they source code as well and we are legally required to include them? 15:13:57 so each individual collection tarball on Galaxy would still include the docs directories/files, but we would ignore/remove them when we pulled the collections into the Ansible package? 15:14:08 I also remember abadger1999 suggesting we would create an `ansible-documentation` package... so it will still be available 15:14:09 community.crypto links to https://docs.ansible.com/ansible/latest/collections/community/crypto/ :) (community.general and community.network will do that after the next release as well) 15:14:22 We can leave the legal questions to legal. Lets assume Legal say it's OK. Is it something we want to do? 15:15:01 I think cutting 10% of the files away is worth it. I don't know whether we should do it at ansible level, or the collection level though 15:15:04 acozine - yes we could just strip them from the Ansible package and leave them in the collection tarball. Or we could remove them from the collection tarball and not have to worry about them at all. Two options 15:15:10 I'd say yes. I doubt anyone generates the documentation locally from the .rst files in the package. 15:15:34 well, we can't control what partners do with their collections 15:15:37 and having an ansible-docs tarball which contains the .rst files and maybe even the generated .html files is probably more helpful to users 15:15:48 We do have the proposal so we can post it on reddit/mailing list and bullhorn (and internally) and see who disagrees 15:16:00 felixfontein: agreed 15:16:07 felixfontein: yeah, that would help the people who want offline docs, too 15:16:13 yep 15:16:31 adding to build_ignore will (slightly) reduce the install time, as well as build time and package size for everybody 15:16:44 we get requests for "I run Ansible in an airlocked env and I want the docs in PDF", and we always say "no, because they will be out of date before you even get them" 15:16:49 #info if we remove .rst from Ansible package, we can also create an ansible-documentation package that includes them, and maybe the generated HTML to help those looking for offline docs 15:17:12 but if folks can download an ansible-docs package that matches their ansible package, that would work 15:17:14 I've no ideas on the use-cases for people with offline docs 15:17:25 if someone's interested in which collection's docs/ folder takes up how much space: https://gist.github.com/felixfontein/4186bd343ed93da9c4a5f93a21565ad1 15:17:49 wow 15:18:43 so, sounds like the consensus is: 15:19:11 yes, let's pull the docs out of the ansible package and create a companion ansible-docs package 15:19:26 also .html files are a lot easier to use than .rst, at least for parameters and when generated by antsibull-docs 15:19:44 and our next step is to advertise this plan and let the community point out the pitfalls? 15:19:50 yep 15:19:51 the .rst files contain large HTML blobs which are not very friendly to human readers 15:20:15 yeah, HTML is much more user-friendly 15:20:59 "parsed" rst is almost worse than raw rst, because it looks fine until you get to the complicated bits, and then it's a mess 15:21:17 #agreed - we will propose that we remove all .rst files from Ansible package and provide a separate ansible-docs package that includes the rst files and generated HTML files for offline use. 15:21:47 we've got nine minutes left in the official meeting time 15:21:51 #action socialize this proposal to reddit/mailing lists, and internal Powers That Be for comments etc https://github.com/ansible-collections/overview/discussions/120 15:24:00 #topic speed-reading other topics 15:24:08 hahaha 15:24:21 love it 15:24:41 These are problems we need to solve soon: 15:24:45 my nickel is the splitting of ansible-base from Ansible docs is critical to get started. That will take time and we have a real drop dead date coming in the New Year 15:25:01 1. How to divide docs for ansible-base from docs for the Ansible PyPI package 15:25:12 I agree to you both 15:25:17 samccann: Bullhorn is going out tomorrow UK AM, so I can link the proposal in there 15:25:34 2. How to maintain module redirects into the future 15:26:06 3. How to make releasing Ansible on PyPI an easy "bitflip" process 15:26:27 gundalow: thanks! 15:27:19 I think for the next few weeks/months maybe we should post a "daily question" or "daily proposal" in this channel 15:27:32 I guess 1. depends also on what marketing / ... wants/thinks/... 15:27:47 felixfontein: yes, partially 15:28:38 there's the question of which content belongs on which side of that dividepages "count" as ansible-base 15:28:40 what's the current thoughts about the solution "separate docsites for ansible and ansible-base"? 15:28:42 grr 15:28:45 edit fail 15:29:08 then there's the question of how do we organize the docsite to show multiple versions of both 15:29:25 felixfontein - I think that is the proposal. The url for say 'ansible-base' might change 15:29:31 felixfontein: heh, no solution yet that I know of 15:29:38 :) 15:30:05 it's part of the larger potential re-org of docs 15:30:18 My feeling is this is going to be a big discussion. Do we need a separate session to just focus on this? 15:30:25 the personas 15:30:30 yep 15:30:38 I guess so, and probably you'll also need more people involved in these discussions 15:30:44 true 15:30:48 maybe we end up with `dev-docs.ansible.com` and URLs like that 15:31:15 or maybe we double down on the current organization 15:31:19 so it's a very VERY big pie. Do we have ideas on how to get started? 15:31:23 should content be replicated, or should there be links? there are a lot of docs which fit for multiple personas. 15:31:51 content could be 'reused' aka same content but shows up in both places 15:31:57 if we're going to replicate content, it needs to be single-sourced for sanity/maintenance 15:32:03 if it really is 90% identical that is 15:32:08 yep 15:32:41 samccann: yes, I think we probably need a session to focus on possibilities, needs, ideas, etc. 15:32:44 maybe use tags to say which .rst file belongs to which roles, and then use some code to copy toghether the .rst files for every persona's docsite? 15:33:07 the hard part are files which contain parts that belong to different personae 15:33:08 that's an interesting solution 15:33:26 I guess not all can be split up properly into different files 15:33:48 I think the first thing is to agree on what we want it to look like when it's done 15:33:56 yep. 15:33:58 indeed! 15:34:01 then we can talk about implementation 15:34:27 but for right now, I need to get our garbage cans back in the garage . . . it's snowing here 15:34:32 we can 'chunk' the rst files down so that we can ... 'assemble' them into pages that read smoothly. But it does complicate everything and might cut into our contributions from community 15:34:37 possible 3-6 inches today 15:34:41 AAAHAHAHA 15:34:44 omgosh sorry 15:34:48 gotta love the midwest 15:35:00 I read that as some wonky analogy acozine was spinning for 'we have to get our ducks in a row' kinda thing 15:35:11 let's endmeeting then 15:35:20 quick open floor, just in case? 15:35:29 #topic open floor 15:35:30 Nothing else from me 15:35:32 i'll do it. go rescue your trash 15:35:40 samccann: thanks! 15:35:42 actually, I have something :) https://github.com/felixfontein/ansible-basic-sphinx-ext 15:35:48 Anyone have anything to add? comments? docs issues or ideas? here's the time to bring it up? 15:36:01 it's a small sphinx extension which contains the minimal amount of stuff to make antsibull-docs output look good 15:36:09 ooo nice 15:36:11 (and it's essentially theme-independent) 15:36:31 So how do you envision this is used? 15:36:32 it's a lot easier to use than the ansible sphinx theme, since you can chose whatever theme you prefer 15:36:49 #link https://github.com/felixfontein/ansible-basic-sphinx-ext 15:37:16 I think it would be good to use it instead of having copies of the .css and lexer plugin lying around everywhere 15:37:43 for that it should probaly move to gh.com/ansible-community though :) 15:38:03 and it would be another dependency for the docs build, and possibly zbr's sphinx theme 15:38:58 (so far I haven't pushed it to pypi, so right now it's a bit harder to use) 15:39:02 So would a collection owner possibly use it if they wanted to generate their own docsite somewhere? 15:39:25 yes. I've used it for the latest version of https://ansible.fontein.de/ 15:39:44 (source https://github.com/felixfontein/felix-ansible-docsite) 15:39:52 #info this could be used to help collection owners create their own docsite - https://ansible.fontein.de/ 15:40:01 #info source https://github.com/felixfontein/felix-ansible-docsite 15:40:41 So... this plus any sphinx theme plus antsibull-docs gives a docsite? 15:40:48 for that docsite, I only add one additional line of css (which makes the theme's content area full-width), besides that it's the standard rtd theme 15:41:07 kewl 15:41:27 that makes it pretty simple to create your own docsite, you don't have to make sure the lexer is around and/or you include the correct CSS to make the parameter tables look good 15:41:56 yeah it does seem helpful to me. 15:42:00 or even include the full ansible sphinx theme (https://github.com/ansible-community/sphinx_ansible_theme), which has a lot of stuff that you usually don't want 15:42:59 yeah I see the ansible sphinx theme being helpful to us on docs.ansible.com so everything has the same look/feel... especially as we consider splitting by persona etc. 15:43:16 but your's is helpful for collection owners etc. 15:43:33 samccann: indeed, and for subprojects of ansible like ansible-lint, molecule, ...; but for some random small collection docsite it's total overkill and hard to use :) 15:43:43 * samccann nods 15:44:12 so next step on this? Do we find collection owners to review it? Do we move it to community as you said earlier (and who would approve that?) 15:44:32 I think it would be nice to move it to github.com/ansible-community 15:45:15 those parameter tables need rework anyway as they should not use "tables", as they are not compatible with narrow screens. 15:45:17 I also would like to polish it a bit, like add a CSS build process (so the final CSS is small, and I can use sass instead of plain CSS for the input) 15:45:21 is it worth bringing up in the community meeting to see if others in the community want to use it? 15:45:46 zbr: yep 15:46:19 samccann: feel free to add any new features directly to the theme. it can be be very useful to have an unified theme that we can all reuse. 15:46:20 I guess it could also come with antsibull-docs, but I don't want to couple it to it that tightly 15:46:38 (the tables are generated by antsibull-docs) 15:47:38 zbr: agreed 15:48:07 t. is on vacation this week (or parts of it), right? 15:48:33 could be... I lost track 15:49:05 anyway, I'll add it to the community meeting agenda 15:49:10 antsibull-docs - could it 'use' this in the future once it's final? So not included directly 15:49:49 ok sounds good 15:50:46 samccann: if the extension is part of antsibull (and the extension is used by all relevant players), one could change how the parameter/return value tables are generated and look like without forcing everyone to update their CSS, because both CSS and HTML generation live in the same repo 15:50:55 Yup, Badgers on holiday this week 15:50:59 (if they are separate repos, it's still easy to coordinate, but people need to upgrade both) 15:51:44 ok 15:53:43 ok are we winding down here? 15:53:56 from my side, yes 15:54:06 just added it to https://github.com/ansible/community/issues/539#issuecomment-712952897 15:54:21 kewl thanks 15:54:28 gonna end this meeting now 15:54:41 #endmeeting