16:01:59 #startmeeting Docs Working Group aka DaWGs 16:01:59 Meeting started Tue Mar 2 16:01:59 2021 UTC. 16:01:59 This meeting is logged and archived in a public location. 16:01:59 The chair is acozine. Information about MeetBot at http://wiki.debian.org/MeetBot. 16:01:59 Useful Commands: #action #agreed #halp #info #idea #link #topic. 16:01:59 The meeting name has been set to 'docs_working_group_aka_dawgs' 16:02:02 ah cool 16:02:03 #topic opening chatter 16:02:11 bom dia, abadger1999 16:02:20 #chair abadger1999 samccann 16:02:20 Current chairs: abadger1999 acozine samccann 16:02:22 \o 16:02:25 * dericcrago_ waves 16:02:28 who else is around? 16:02:34 #chair felixfontein dericcrago_ 16:02:34 Current chairs: abadger1999 acozine dericcrago_ felixfontein samccann 16:02:57 hi! 16:03:36 andersson007_: dmsimard gundalow baptistemm briantist cyberpear madonius tadeboro tributarian you folks talking docs today? 16:03:40 felixfontein: hi! 16:03:53 hi sure 16:03:58 Hi all! 16:04:00 Busy today. 16:04:05 \o 16:04:14 cyberpear: we'll miss you 16:04:27 #chair briantist tadeboro dmsimard 16:04:27 Current chairs: abadger1999 acozine briantist dericcrago_ dmsimard felixfontein samccann tadeboro 16:04:30 welcome everyone! 16:04:56 * gundalow waves 16:05:11 for anyone who is watching this chat and thinking, "I don't see my name, I guess I'm not invited . . . " YOU ARE INVITED TOO 16:05:30 we ping folks who have participated recently 16:05:32 just say something and you'll get chaired. 16:05:58 and we welcome everyone, whatever your skill or experience level 16:05:59 #chair gundalow 16:05:59 Current chairs: abadger1999 acozine briantist dericcrago_ dmsimard felixfontein gundalow samccann tadeboro 16:06:06 gundalow: hi! 16:07:02 official agenda begins with: https://github.com/ansible/community/issues/579#issuecomment-784355726 16:07:38 o/ 16:07:44 gwmngilfen: hi! 16:07:47 #chair gwmngilfen 16:07:47 Current chairs: abadger1999 acozine briantist dericcrago_ dmsimard felixfontein gundalow gwmngilfen samccann tadeboro 16:08:10 #topic `devel` docs for the community package 16:08:51 background: the old all-in-one-repo ansible package published `devel` docs that reflected the newest features and latest changes to documentation 16:09:19 with the collections-based Ansible package, that model needs to change abit 16:09:30 s/abit/a bit 16:11:26 so last week's community meeting agreed that `devel` docs should never include pre-release versions of individual collections - any collection-based docs called `devel` should be full releases 16:11:55 based on our previous discussions, we are converging on this definition of `devel` docs for the Ansible package: 16:12:53 I see devel as "things that would go into the next major Ansible version if the freeze would happen at the time of documentation rendering" in collection world. 16:12:55 Include `devel` documentation for ansible-core, plus docs for the most recent full release of each collection approved for inclusion in the Ansible PyPI package 16:13:20 tadeboro: that's a nice description 16:13:41 except for the underlying ansible-core version . . . . 16:13:48 thinking out loud: the latest version of the collection is not always the right one, depending on version boundaries 16:14:00 if freeze happened today, it would still include ansible-core 2.10, not 2.11 16:14:13 by boundaries I mean: https://github.com/ansible-community/ansible-build-data/blob/main/3/ansible-3.build 16:14:14 dmsimard: what do you mean by "the right version"? 16:14:29 This is why I said next major version that has almost no boundaries. 16:14:59 dmsimard: ah, you mean the right version for the next Y release (in an x.y.z pattern)? 16:15:11 you're right 16:15:12 acozine: going with the link above, community.general is >=2.0.0,<3.0.0 -- so pretend c.g released a 4.0, would that be appropriate for devel ? 16:15:20 yes 16:15:35 I think we could target the proper version of ansible-core. 16:15:37 dmsimard: but that's for the *current* major Ansible version, not for the next major version 16:15:38 If we want to. 16:15:58 felixfontein: so should we have an ansible-build-data for devel ? 16:16:07 I think we discussed last time in community that we would have 'the most recent stable release' until the point where Ansible 4 versions are defined 16:16:08 yeah, we're still at the "what do we want" stage 16:16:23 dmsimard: no, just use ansible.in from the newest version in ansible-build-data 16:17:01 samccann: I think we didn't had a limit, so it will continue with newer versions also after Ansible 4 16:17:34 felixfontein ah ok, so 'devel' would never lock to Ansible 4 prior to release.. I missed that point 16:17:50 samccann: no, devel is devel and will stay devel ;-) 16:17:51 my sense is that users want a way to see the documentation for the most recent (full) version of each of the collections in the package, to answer the question, "What would I get if I overrode the packaged version of Collection X with the most recent released version of Collection X from Galaxy?" 16:18:52 And I think that "next major Ansible release" would contain those versions. 16:19:34 acozine - we have to decide are we filling in for docs missing in Galaxy (what your statement suggests to me) or what the next version of Ansible the package may include 16:19:41 tadeboro: yep 16:20:08 tadeboro: or more precisely, the next major version of ansible that hasn't reached beta yet 16:20:15 samccann: what differences do you see between those two scenarios? 16:20:43 can the `devel` docs do both? 16:20:52 acozine - that might have been the difference I mentioned above, where once Ansible 4 has some details, devel would follow that 16:21:15 ah, so in the period between the freeze and the release of Ansible 4? 16:21:27 So for example, c.g 5 comes in Ansible 4 at alpha time. Say by rc1, c.g. is now 6. devel would still show 5 16:21:45 yeah sort of like that. Not saying that's correct, that's just what I had in my mind 16:21:48 samccann: devel should show 6 then IMO 16:22:00 gotcha, that makes sense 16:22:02 it would be easier I think to do as felixfontein just said 16:22:19 we could publish docs for 4 as soon as we know the versions 16:22:22 and you said - make devel always track the most recent stable version in Galaxy for included colections 16:22:30 just don't update the `latest` symlink until release 16:23:10 acozine that's not something we've done in the past (create a url-based release before the actual release). I'd rather just stick with devel always following galaxy latest 16:23:26 sounds good 16:23:28 then if we want an rc docs candiate, we can do that, but not before 16:23:38 s/candiate/candidate/g 16:23:42 so devel would also contain docs for collections that will be included in the next major ansible release, and it will no longer have them if that collection is removed form the next major ansible release (even if the current release still has them) 16:23:48 Yeah, I think when beta comes out, ansible 4 and devel could potentially start diverging. 16:24:28 abadger1999: definitely, since also minor collection releases get no longer included until x.1.0 16:24:29 abadger1999 which is what has always happened with devel, as soon as the stable branch is pulled, devel is then reflecting the NEXT release after that. 16:24:39 samccann: exactly 16:24:48 I do not see the problem with divergence after freeze. 16:24:55 in that sense, it would be continuing a long tradition :) 16:25:15 yep, and as a result, users expect that behavior 16:25:45 a long and GLORIOUS tradition! ;-) 16:25:58 are we ready to info something here? 16:25:59 heh 16:26:09 we might even be ready to . . .. 16:26:11 VOTE! 16:26:15 VOTE!!! 16:27:52 Vote: +1 for `devel` package docs including the next version of `ansible-core` (the `devel` branch up to the next core release, the stable release branch up to the next package release) plus the most recent full versions of any collection included in the package 16:28:26 not sure I understand that part on `the stable release branch up to the next package release` 16:28:31 mmmm 16:28:44 yeah, we should discuss 16:28:50 here's hte rhythm i had in mind: 16:30:00 Ansible 3 releases based on core 2.10, /ansible/latest/ updates to /3/; ansible-core docs show 2.11 in `devel`; ansible docs show 2.11 in `devel` plus most recent release from Galaxy of included collections 16:30:11 then ansible-core releases 2.11 16:30:37 ansible-core docs show 2.11 as `latest` and start tracking 2.12 as `devel` 16:31:09 one correction - ansible-core has no latest, it's version only 16:31:15 ansible docs show 2.11 plus latest collections as `devel` until 4.0.0 comes out 16:31:21 samccann: ah, I forgot that 16:31:21 `latest` is being reserved for Ansible package docs 16:31:27 thanks 16:31:53 after Ansible 4.0.0 is out, the ansible `devel` docs start showing core 2.12 and the cycle begins again 16:31:58 hmm, why not have ansible/devel show ansible-core 2.12 + latest collections? 16:32:48 well, we could 16:33:11 otherwise we should probably all the time use the latest ansible-core release (as opposed to devel branch) 16:33:27 I guess it's simpler that way 16:33:36 I though that ansible/devel would show docs for ansible-core devel + docs for latest stable version of included colletions. I am assuming here that ansible-core and ansible releases are synced. 16:33:44 switching between released version and devel sounds complicated 16:33:50 true 16:33:54 yeah this sounds simpler 16:34:05 tadeboro: there will probably always be a few weeks between them 16:34:15 tadeboro: well, we'll see when we do the first pair of releases 16:34:22 Another scenario that's close would be ansible/devel shows what will be in ansible-4 until ansible-4.0.0beta1. Then it will show what's in ansible-5. (But that kinda means we might want to publish ansible/4/ docs at beta time which we haven't done in the past). 16:35:21 my nickel would be to keep is simple 16:35:39 devel is core devel and Ansible collections latest and stays that way 16:35:49 okay, I revise my proposed vote text . . . 16:36:01 simple for me is: either 1) always use ansible-core devel, or 2) always use the latest ansible-core release 16:36:18 This is why I proposed "all things devel". We will find enough problems even with the simplest approach ;) 16:36:23 cyb-clock says 36 minutes into the meeting and this topic 16:36:25 VOTE: +1 to `devel` docs for /ansible/ always showing `devel` branch of ansible-core plus most recent Galaxy versions of included collections 16:36:47 +1 16:36:49 +1 16:36:56 +1 16:37:00 +1 simplicity wins 16:37:21 makes sense, +1 16:37:35 +1 fwiw, i also like simplicity (and probabl makes the analytics easier to parse too) 16:37:39 +1 16:37:46 wfm :-) 16:38:02 phew, i was worried you were mulling over some dreaded technical objection abadger1999 16:38:12 hehe :) 16:38:56 abadger1999 only brings the highest-quality organic technical objections, mind you :) 16:39:06 I see several options which are all possible :-) I did mull this over but I don't see any problems :-) 16:39:25 I figure you made the `latest` docs work, this can't be harder than that was 16:39:58 any other thoughts about `devel` docs before we move to a new topic? 16:40:33 #agreed devel` docs for /ansible/ always showing `devel` branch of ansible-core plus most recent Galaxy versions of included collections 16:40:45 samccann: thanks 16:41:00 future readers of the minutes are grateful 16:41:05 :) 16:41:07 #info we chose the simplest approach for the Ansible devel docs 16:41:27 #topic collections /docs/ folder 16:41:34 get out your rotten tomatoes, folks 16:42:02 if you throw them, you'll just have to clean up your own screen afterwards. 16:42:06 I still don't have any info on the roadmap for collections/Galaxy/AH/NextGen 16:42:08 heh 16:42:42 so I don't see a way to make progress on this topic yet 16:42:45 mea culpa 16:42:48 I don't have any roadmap info either 16:43:07 do we have any info on what galaxy/AH is planning? 16:43:09 do we know who to talk to, as in have we identified who the decision maker(s) are? 16:43:15 or even thinking on this topic? 16:43:25 Is the advice just "add `./docs/` MD or RST" 16:43:44 gundalow: whose advice is that? 16:43:55 felixfontein: mine that I've made up just now :P 16:44:03 right now I'm not aware that anyone is giving collection owners advice about what to put in that folder 16:44:07 When I was preparing the collection for certification, I was instructed to use md in docs folder. 16:44:09 gundalow: we'd want a set subdir probably for .rst that will be brought back into docs.ansible.com, but that conflicts with the /docs/ md that is already in use in some places 16:44:18 and the docs/rst that is already in use in some places 16:44:19 tadeboro: by whom? 16:44:27 felixfontein: no info. I don't believe it's even got onto the potential features, let alone how that dir should be used/structured 16:44:37 whoever told you that is someone we should speak with 16:44:39 that is our guidelines in our docs - .md in that folder as that is what AH wanted 16:44:49 heh 16:44:51 there's a galaxy topic at contributor summit, I would like to think we'd learn more there 16:45:02 ooh, that's good news 16:45:14 * samccann feels like she was just called to the principal's office.. and acozine is the principal! 16:45:15 dmsimard: will there be someone from the galaxy/AH team(s)? 16:45:32 * abadger1999 will have to duck out of this meeting in 15 minutes 16:45:38 I think of myself more as the janitor 16:45:47 felixfontein: I hope so but I don't know (haven't checked or asked) 16:45:57 cyb-clock says we are 'a few' minutes into this topic, 45 minutes into the meeting 16:46:03 heh 16:46:10 IIRC, we had a meeting with Richard Henshall, but this was more than a year ago. 16:46:11 * samccann wonders if cyb-clock should have started a timer 16:46:22 * felixfontein played around a couple of weeks ago with RST code to try to figure out how to get a list of labels a RST file defines (so we could validate that), but was unsuccessful 16:47:06 tadeboro: thanks, I'll put Rich on my list 16:47:36 does anyone here has experience with RST handling code? 16:47:41 felixfontein: list of labels? oh, to make sure we don't duplicate across collections 16:47:50 acozine: exactly... 16:47:51 decision makers would be rich and dylan for sure... coding advice would be some of the galaxy developers themselves 16:48:10 samccann knows more rst nuts and bolts than I do 16:48:11 acozine: resp. to ensure that they conform to the correct format, and simply not include the file in the docs build if they don't 16:48:29 felixfontein - I thought there was going to be a trick of adding the collection name to any labels within those rst files so all labels end up unique? 16:48:57 samccann: yes, but either we need a program which does that (including all references), or at least a program which verifies whether that's actually the case 16:49:03 samccann: right now we have neither 16:49:06 Using intersphinx, I think? 16:49:08 ah gotcha 16:49:20 abadger1999: that only helps if we have different docsites per collection 16:49:31 intersphinx wouldn't work I don't think because we are bringing their rst files into docs.ansible.com so to speak 16:49:51 or.. what felixfontein said ..clearer and with less words ;-) 16:50:03 simply adding .rst files into the general doc tree would be the easiest way to implement this - if we can enforce that the .rst files stick to our label naming rule 16:50:23 (also having a way for collection authors to lint their .rst files for using the correct labels would be nice :) ) 16:50:32 #info TBD what we can do with the collection /docs/ folder as some collections use .md there, others use .rst to repeat module level docs, neither of which work with docs.ansible.com today 16:50:56 I think we could make intersphinx work but I agree that it is easier from our side if we can just get collection owners to follow convention. 16:51:03 felixfontein - don't some of our ansible-test sanity test for that already? 16:51:03 we could define a new /docsite/ folder, or a subfolder /docs/docsite/ 16:51:19 samccann: they don't - they run rstcheck, but that doesn't care about labels 16:51:25 yeah, I was thinking we define `docs/docsite/rst/` so it matches what's in the main docs 16:51:43 felixfontein - something checks for repeat labels because I've gotten those errors 16:52:06 samccann: that's the docsite build, and it only works in ansible/ansible and not in collections 16:52:12 You will get repeat label errors from sphinx-build itself. 16:52:23 felixfontein - ah gotcha 16:52:33 abadger1999: that's nothing that collection owners want to run to check their collection :) 16:52:39 Yep 16:52:54 (also just because a label isn't in use right now doesn't mean it is still not in use in two hours, when foo.bar released a new version) 16:53:10 #info we would need some script to check for properly formatted labels at the collection rep o CI itself 16:53:36 so we need to either separate the builds into different docsites, or have some validation in form of "list all labels in this .rst file (and make sure they have the correct prefix)" 16:53:42 #info we'd also need 'something' to create unique labels once they are brought into ansible docs build (e.g. prepend collection name) 16:53:56 I would *expect* the second to be easier to implement, but RST is a beast... :) 16:54:15 and docutils seem to be pretty complex 16:54:48 cyb-clock says 12 minutes into current topic, 4 minutes left to the 'official' meeting time 16:55:04 Stack Overflow suggests this: https://stackoverflow.com/questions/26666859/how-do-i-print-all-labels-that-are-defined-in-a-sphinx-project 16:55:18 it took me some time to figure out how to use docutils to load a .rst file and walk its node tree, but I still have no clue how to identify labels... 16:55:33 as a way of extracting labels, but I don't understand where in the process that happens 16:56:29 I once wrote a domain for Sphinx, but I am afraid to go read over my notes because that process was not fun. 16:57:08 tadeboro: the limited experience I had with sphinx and docutils internals so far lets me feel your anxiety ;) 16:57:23 in some ways Sphinx is well-named - like the mythical beast, it's not very interactive 16:57:34 or perhaps I should say, sociable 16:57:36 are all 'fixed' labels in RST defined by `.. _xxx:`? 16:57:44 felixfontein: yes 16:58:01 ok, in that case some text-based linting could be done 16:58:05 somewhat ugly, but should do the job :) 16:58:20 (and can be improved if it turns out to miss some edge cases) 16:58:24 working code wins 16:58:57 though elegant working code wins even more 16:59:08 okay, we're at the one-hour mark 16:59:22 using proper RST parsing code would be even better, but docutils scare me too much to try again ;) 17:00:07 if you have time to try it out, that would be awesome felixfontein 17:00:14 acozine: I'll try to hack something together 17:00:15 should we hop to the two items felixfontein added to the agenda? 17:00:19 sure 17:00:39 #topic infoblox scenario guide 17:00:41 #topic PR 73676 17:00:47 heh 17:00:47 heh, sorry 17:00:50 same topic, though 17:00:50 #link https://github.com/ansible/ansible/pull/73676 17:01:20 that's essentially adding a note that the inventory script included in community.general only works in very special circumstances 17:01:28 LGTM 17:01:40 and adds that people should stop using it ;) 17:01:54 heh 17:01:56 merged 17:02:14 thanks a lot! I'll create a backport to stable-2.10 later 17:02:18 #topic PR 73170 17:02:21 #link https://github.com/ansible/ansible/pull/73170 17:02:21 https://github.com/ansible/ansible/pull/73170 | open, created 2021-01-09T22:11:24Z by felixfontein: Use antsibull sphinx extension [affects_2.11,core_review,docs,support:core,test] 17:02:37 This one we can put up on test to verify the three doc varieties work with the PR before we merge 17:02:56 sounds good! 17:03:08 it should not change the resulting docpages, but who knows :) 17:03:12 kewl 17:03:23 Should we open the floor next? 17:03:31 * samccann those went quick! 17:03:34 sure 17:03:34 the CSS will look a bit differently since parts move to other places, but everything else should stay identical - and the combined CSS should give the same result 17:03:56 * acozine shivers at the idea of troubleshooting combined CSS 17:03:57 ok thanks. we'll ping here once it's all up on test 17:04:03 cool, thanks a lot! 17:04:08 #topic open floor 17:04:20 btw, how's the stable-2.10 backport of the docsite split PR going? 17:04:35 any news on that, resp. a chance of it getting merged? 17:04:39 just quickly, I didn;t see this in last week's minutes, but the detailed writeup of the survey is up on my blog: https://emeraldreverie.org/2021/02/23/docs-survey-2020-results/ 17:05:09 gwmngilfen: cool! 17:05:17 i know acozine has plans for a wider-consumption take, but if you want the gritty modelling, there it is :P 17:05:24 #info link to docs survey blog - https://emeraldreverie.org/2021/02/23/docs-survey-2020-results/ 17:05:36 the backport (https://github.com/ansible/ansible/pull/73637) is still failing CI 17:05:36 https://github.com/ansible/ansible/pull/73637) | open, created 2021-02-17T17:39:23Z by acozine: WIP: Backport of Split Ansible docs from core docs (#73616) [WIP,affects_2.10,backport,ci_verified,docs,needs_triage,stale_ci,support:core,test] 17:06:52 acozine: have you tried removing the two ignore.txt lines? 17:07:08 honestly, I haven't looked at it this week at all 17:07:34 because it only fails because there are two ignore.txt lines for a file that no longer exists 17:07:38 removing them should fix that 17:08:24 ignore.txt? or .gitignore? 17:08:53 ignore.txt 17:09:02 test/sanity/ignore.txt 17:09:12 ah, okay . . . that's an easy fix 17:09:15 thanks felixfontein 17:09:28 lines 7 and 8 in there 17:09:28 I'll update that and try to get it merged and published in the next day or two 17:09:42 sounds good :) 17:10:30 what other questions are out there? 17:10:41 comments, suggestions, ideas, feedback on the docs? 17:11:21 as a reminder, everyone is welcome to add items to our agenda 17:11:38 just put a comment on https://github.com/ansible/community/issues/579 17:12:14 and each week we do an open floor where everyone is welcome to ask questions, look for advice, bring PRs or issues up for review 17:12:56 hearing no other items for today's open floor . . . 17:13:02 thanks abadger1999 briantist dericcrago_ dmsimard felixfontein gundalow gwmngilfen samccann tadeboro 17:13:17 o/ 17:13:29 see you here in chat any time 17:13:31 OOOHHHH 17:13:43 Thanks 17:13:45 Thanks all! 17:13:47 next week's DaWGs meeting will probably be overridden by the Contributor Summit 17:13:52 right, isn't that next Tuesday? 17:13:56 yup 17:14:12 yes 17:14:25 #info Contributors Summit next week https://hackmd.io/uZDSLOOdS1Kx0xfZVIATmQ 17:14:42 so we'll have one week of informal discussions and next formal meeting will be Tuesday March 16 17:15:01 folks in Europe, can you let me know when your time changes again? 17:15:16 not when your's changes ;) 17:15:18 soon it will be time to adjust our meeting for Summer! 17:15:37 I know, it's so confusing and silly . . . 17:15:42 March 28th apparently 17:15:47 felixfontein: thanks 17:15:57 I never remember :) 17:16:00 acozine: You expect us to know that? I know things changed when I miss my first meeeting with US folks ;) 17:16:04 I have no idea when ours changes 17:16:25 but for the next few weeks we probably need special warnings in the channel 17:16:28 wasn't it like the coming weekend or so? 17:16:34 maybe? 17:16:36 I don't know 17:16:39 but I'll find out 17:16:51 * felixfontein still ponders on changing his computer's time to UTC, makes it easier to remember Ansible meetings ;) 17:17:12 (or well, I think it already uses UTC, but the display time is CET/CEST :D ) 17:17:15 March 14th in the USA 17:17:39 okay, I'll put a note on my calendar to do reminders the day before with local times emphasized 17:17:42 ah, so after the community meeting 17:18:03 and we can change the UTC time later this month 17:18:16 al right, thanks again, folks! 17:18:24 #endmeeting