14:31:33 #startmeeting Docs Working Group aka DaWGs 14:31:33 Meeting started Tue Jun 16 14:31:33 2020 UTC. 14:31:33 This meeting is logged and archived in a public location. 14:31:33 The chair is acozine. Information about MeetBot at http://wiki.debian.org/MeetBot. 14:31:33 Useful Commands: #action #agreed #halp #info #idea #link #topic. 14:31:33 The meeting name has been set to 'docs_working_group_aka_dawgs' 14:31:40 who's around? 14:32:16 me me me!!! 14:32:24 o/ 14:32:25 #chair felixfontein samccann 14:32:25 Current chairs: acozine felixfontein samccann 14:32:50 * Guest63935 listens from bed; don't expect much talking from me today ;-) 14:33:02 hi :) 14:33:11 Guest63935: who are you? 14:33:13 Am I still guest.... 14:33:15 * Guest63935 relogs 14:33:18 yes 14:33:20 (it's abadger1999) 14:33:23 ah :D 14:33:24 but your name is showing now 14:33:31 are you feeling any better? 14:33:33 oh toshio!! bummer on the illness... hoping it's not THE ILLNESS 14:33:46 oh, you're sick? get better soon! 14:35:14 I'm feeling better. I'll probably be back workin tomorow 14:35:50 It was an antibiotic allergy 14:35:59 Guest63935: oh, ouch! 14:36:15 it sucks when the things that are supposed to support your health end up undermining it 14:36:49 Yep :-) 14:37:08 * Guest63935 figures out what's wrong with his freenode account while the meeting continues 14:37:11 heh 14:37:19 #topic priority PRs 14:37:36 first listed priority PR is https://github.com/ansible/ansible/pull/69202, which we merged yesterday 14:38:00 kudos to samccann for corralling a huge amount of information into a readable page 14:38:12 dang I pulled the wrong PR for review. it's not that one. it's the R() one 14:38:21 ah! okay 14:38:26 still, you deserve some props 14:38:28 #link https://github.com/ansible/ansible/pull/69832 14:38:37 indeed! just saw that this morning, it's awesome! 14:38:42 and folks should take a look at those published pages and suggest refinements 14:38:59 as contributions to collections start coming in 14:39:09 yep, got some feedback already to update that page but more always welcome 14:39:21 meanwhile on R() - see the last couple of comments 14:39:28 * gundalow waves 14:39:31 Woo hoo! Nice work 14:39:46 #chair gundalow 14:39:46 Current chairs: acozine felixfontein gundalow samccann 14:40:28 andersson007_: briantist cbudz cyberpear madonius Pilou shaps tadeboro thedoubl3j Xaroth zbr zoredache join in any time! 14:40:29 This is the only open question - M() and R() - @acozine - I'm of two minds here - it's a good point that people building their own docsite would need to know they need intersphinx to get them working, but I'm not sure we are/should be in the business of documenting how someone builds their own docsite from module content. I could just add a phrase after that last sentence to say something like "These cross-references to other Ansible 14:40:29 documentation work based on the intersphinx extention'. 14:41:39 which is to say - M() and R() work on our docsite. I'm not sure if we even want to add that it won't work for your own docsite unless you use intersphinx. but wanted to see what others thought 14:42:20 this brings us back to "do we want to package the ansible docsite tools for private/offsite use?" 14:42:33 I don't think it hurts to mention intersphinx (it will probably save at least one person some time when trying to figure out why something isn't working) 14:43:25 acozine: since there are public collections not part of ACD, I think it would be helpful if we'd try to support them (at least if it is not too much work) 14:43:50 yeah, I agree it would be nice 14:44:19 is it currently possible to build collections-only docs? 14:44:36 I mean, to build docs for a collection without building the entire docsite? 14:46:03 antsibull should be (with some munging of the config files) currently usable for third party collection docs. I'm hoping to add some other modes of operation to make it more usable in the future. 14:46:11 but we can simply mention something like "relies on intersphinx" with a link either to our intersphinx config or to the main intersphinx docs 14:46:30 abadger1999: hey, you're back 'as you'! 14:46:39 The functionality is mostly there... it just needs some toplevl code to take command line arguments from the user and pass it to the right places . 14:46:51 Yep. figured out the issue :-) 14:47:01 awesome, so this is a current-moment use case (at least, potentially) 14:47:20 samccann: so I think your suggestion is a good one 14:48:00 #agreed add a link to intersphinx for M() and R() use on third party docsite 14:48:44 next priority PR is 14:48:50 #link https://github.com/ansible/ansible/pull/70064 14:49:36 felixfontein: this is exciting! 14:50:00 is it the last piece of the changelog work? 14:50:41 for c.c, c.g and c.n, that should be the last things moved over from ansible/ansible 14:50:58 the porting guide has some more entries that should go into collections 14:51:27 I don't know who wants to move them, I'm too busy with other things right now :) 14:51:38 So the question I had - when everything was in ansible/ansible - we could hotlink to the module docs from the porting guide. Can we use R() now in collections to do this same thing? 14:54:05 ah 14:54:25 the problem is that R() only works for docs generation, not for changelog generation. you'd have to use raw refs. 14:54:36 We can use :ref: directly in porting guides . 14:54:53 What felix said. 14:54:58 and changelogs are usually read directly as text files, and not necessarily after RST parsing, so I would only use it when necessary 14:55:16 One thing to remember with refs in porting guides... 14:55:19 the porting guides can still have non-automated (from-the-changelogs) content, right? 14:55:27 plain old rST? 14:55:28 the changelog generator treats every fragment's contents as raw RST and does not do any processing (except by putting it into a list item) 14:55:35 Things that eventually get removed lead to broken refs. 14:56:05 So you my have to modify old porting guides when the refs no longer exist 14:56:25 so gist of it is - don't add R() in changelog fragments is what I get from this so far 14:56:45 (One way to solve that could be to only have the porting guide for the current release and link to the versioned porting guide in older releases for older info) 14:56:50 yep 14:56:58 it's probably better. modifying old changelog entries is something I'd like to avoid, changelogs for released versions should be kept frozen IMO (same as the release) 14:57:10 I suspect that most porting guide entries that are *only* the changelog entries won't need to link back to the module docs 14:57:30 not sure I understand that statement ^^ acozine 14:57:58 I asked because the moves felixfontein made had links in the old ansible/ansible porting guide entry, and none in the new changelog fragments within collections 14:58:06 IIRC we agreed that some porting guide entries would need some additional explanation 14:58:42 and that we would add some rST for those directly to the Porting Guide pages, so those pages would be a hybrid 14:58:54 as in 'no longer use module xxx but use modul xxx 14:58:59 * gundalow -> afk 14:59:05 we would have "plain vanilla" entries that only contain the changelog entries 14:59:34 and that would be a LOT of links to add manually to ansible (ACD) after the fact. so my nickel is we just give up on hotlinks in the porting guide entries that come from changelog fragments. 14:59:39 ahh, for deprecations . . . 14:59:49 yeah, that seems like a lot of extra work 14:59:56 Maybe we add a hotlink to the start of each collection section so the user can go there for whatever is under that section. 15:00:14 (for the ansible (acd) porting guide ^^^) 15:00:53 yeah, I need to do a test run on the whole changelog/porting guide system now that it works . . . I haven't looked at the actual output 15:00:58 I like your idea samccann 15:01:39 do we need a formal POLL??? 15:01:42 heh 15:01:43 maybe 15:01:48 * samccann learning from how felixfontein runs meetings 15:01:56 :D 15:02:05 it depends on what the result of the poll is needed for 15:02:12 I was thinking that whatever we do about links from the changelogs, we're moving ahead with the PR under discussion 15:02:23 POLL - Do you agree that changelog fragments should not use R() and M() and any such linking? 15:02:32 for c.g/c.n I wanted to have some agreed things so we can start release planning, and if people complain about something we can point to the decisions ;) 15:02:36 +1 15:02:40 +1 15:02:41 +1 15:02:55 (for 2.10 ) +1 15:03:24 meanwhile shall I merge 70064? 15:03:42 I can't remember how you summarized the poll results? 4 in favor, 0 against 15:03:57 (acozine yeah this doesn't hold up that PR, just wanted to have the related discussion) 15:04:31 #agreed changelog fragments should not use R() and M() and any such linking as it doesn't work in raw rst, where the user will see it per collection. 15:05:34 So there are other changelogs from the sound of it that need to be moved. Do we want to tackle that on our own? go bug the collection owners? how do we want to remedy that situation? 15:05:56 I heard that a lot of 1.0.0's are released this (or next?) week 15:06:12 I guess these are mainly the ansible Supported collections 15:06:45 yes, i think there are quite a few releases planned for this or next week 15:06:47 yeah but I see some entries that might be part of that 1.0.0 release batch. 15:07:03 exactly\ 15:07:23 I guess there are also a lot of repated changelog fragments from ansible/ansible that would belong in these; I have no idea whether anyone tried to copy them there, though 15:07:42 (I did that work for c.c, c.g and c.n and I'm happy to not having to do it again ;) ) 15:07:50 repated? 15:07:56 oh repeated 15:08:11 reaped 15:08:30 my nickel - we ask collection owners to do the right thing. If they don't, such is life 15:08:41 https://github.com/ansible/ansible/pull/68498#issuecomment-609404786 15:09:21 and one that isn't mention there: https://github.com/ansible/ansible/pull/69491 15:10:02 btw, do you know whether the ansible collections use/plan to use antsibull-changelog, or something else? 15:10:44 they are using antsibull-changelog. I don't know if they've done it yet or not, I'll check later today 15:11:01 ok, thanks! 15:11:06 that's good 15:11:25 merged 70064, BTW 15:11:35 yep. means we will have several changelog.yaml's to work with! 15:12:05 let the fun begin! 15:12:09 acozine: saw it, thanks a lot! 15:12:36 Oh, I had a thought related to this... currently the ansible-2.10.tar.gz won't include the changelog. Do we want it? If so, I'll need to add something to build that to the build process. 15:12:50 felixfontein: thank you for the work! 15:12:52 ok I'm getting myself confused here. I see in the current `devel` 2.10 porting guide, all the modules are linking to 2.9. Anyone know why? 15:13:05 samccann: link? 15:13:20 https://docs.ansible.com/ansible/devel/porting_guides/porting_guide_2.10.html#command-line 15:13:21 abadger1999: good question. did it contain the changelog in older versions? 15:13:48 maybe it's intersphinx 15:13:51 just hover over any module link and they are all 2.9. I checked the 2.9 porting guide in 2.9 and they all point to... 2.9. 15:13:57 huh, that's weird 15:13:59 because the links don't exist in devel, it looks where it can find the link 15:14:03 ah, of course 15:14:07 ah right! 15:14:19 once we have module docs again, we'll have to update those 15:14:22 at least I guess that's what intersphinx is doing, I have really no idea what it does ;) 15:14:32 felixfontein: yes, ansible-2.9 includes a build changelog. 15:14:39 *built changelog 15:14:46 so i'm still of the mind - we ask collection owners to do the right thing and whatever happens, happens. But then I see others have moved things for people. so maybe I'm taking the lazy way out? 15:14:51 abadger1999: I guess 2.10 should then have one too 15:15:00 #topic changelogs in the collections ecosystem 15:15:26 * acozine was a little late on the topic change . . . 15:15:31 #info we still have a bunch of changelog fragments in ansible/ansible that really should be in their appropriate collections 15:15:45 abadger1999: I think it would be nice to include a changelog in the tarball for 2.10 15:15:56 #info the fragments have mostly been deleted from ansible/ansible, but probably not been inserted in the corresponding collection 15:16:10 heh didn't know that part, thanks! 15:16:11 acozine: Okay, probably won't make alpha1 but I'll work on putting it in before beta and final. 15:16:28 it's not the highest priority piece, for sure 15:17:21 abadger1999: that still needs a ACD changelog generator first I guess ;) I'll re-start working on that soon, once all the ansible/ansible and collection releasing work is out of the way 15:17:46 thanks felixfontein ! 15:17:56 felixfontein: hehe, I guess I'm getting ahead of myself, then. Thanks felixfontein :-) 15:18:44 ok so changelogs in ansible/ansible have been deleted, but not all of them... and we don't know if anyone moved them to their related collections except for what felixfontein has done. Is that correct? 15:20:06 samccann: I think the remaining ones should mostly stay. I'm not sure how extensively they were combed, maybe there's still something in there that shouldn't be, but I think most that are left should stay in ansible/ansible 15:21:08 #info https://github.com/ansible/ansible/issues/67654 and https://github.com/ansible/ansible/pull/69491, which says it's #6 but doesn't reference the other 5 15:21:51 i'm once again just lost. So https://docs.ansible.com/ansible/devel/porting_guides/porting_guide_2.10.html#command-line has a bunch of entries that don't belong (grafana, vmware, etc) but I can't find them in the repo here -https://github.com/ansible/ansible/tree/devel/changelogs/fragments 15:22:23 oh nevermind 15:22:32 duh.. porting guide is manual in ansible/ansible.. doh! 15:22:38 we aren't building the porting guides from changelogs yet 15:23:20 exactly :) 15:23:45 but both changelog fragments and porting guide have the same problem, except that the changelog has already been cleaned up 15:23:46 ah, this shows 5 of the 6 changelog removal PRs: https://github.com/ansible/ansible/pulls?q=is%3Apr+reap+in%3Atitle+is%3Aclosed 15:23:48 ok so changelogs were removed, may not have been moved to their collections. Do we do anything about this? 15:24:10 #info this shows 5 of the 6 changelog removal PRs: https://github.com/ansible/ansible/pulls?q=is%3Apr+reap+in%3Atitle+is%3Aclosed 15:24:35 for sure we should notify the collections owners 15:24:36 maybe remind collection owners, "please try to collect all changelog fragments added after 2.9 for content in your collection, so the changelog for ACD 2.10 will mentioned *everything* changed after 2.9.0" 15:24:50 sounds good to me 15:25:08 #action samccann gundalow - remind collection owners, "please try to collect all changelog fragments added after 2.9 for content in your collection, so the changelog for ACD 2.10 will mentioned *everything* changed after 2.9.0" 15:25:27 anything else for changelogs before we move to the same problem for porting guides? 15:25:49 (we have 5 min left) 15:26:00 I'm good to move on 15:26:08 me too 15:27:11 for porting guides I think we do a test run of the changelogs-to-porting-guides pipeline, and once it works decently, we have one PR that removes all the duplicated info 15:27:56 #topic old porting guide entries in ansible/ansible 15:28:23 we'd have to both remove and likely move 15:28:44 my guess is many folks don't have the porting guide entries in their changelog fragments as that's a fairly new thing (new ish ) 15:29:37 I thought we were pulling from existing changelog categories for hte porting guide 15:29:44 probably it's a good idea to remove them first, like for the changelog fragments, and then tell people to extract the entries that are relevant for their collections from the diff 15:29:54 acozine: AFAIK we do 15:30:12 yeah my thought is that they don't exist. So if we remove from one, we'd have to create the changelog fragments to match for each in their respective collections 15:30:14 btw: should major changes be part of porting guide, or not? 15:30:30 I think major_changes should be, because we had "noteworthy module changes" in the old porting guide 15:30:43 let's try it and see how long the list gets to be 15:30:45 Yeah I think major_changes should be in the porting guide 15:30:59 if it's too huge, we can link to the changelog, I guess 15:31:37 I guess the fallback for 2.10 is we just manually move the current manual 2.10 ansible/ansible porting guide sections to the ACD porting guide. 15:31:47 though it would make it messy for sure. 15:32:09 I don't think we can link to the changelog. let me try to explain better. 15:32:42 Today, there is a batch of vmware* modules in the 2.10 porting guide. My guess? there are no matching changelog fragments in the vmware collection. 15:33:10 so when we generate ACD porting guide, they won't be there 15:33:14 I'm not sure how that manual step will work with the build process 15:33:23 yeah, I think we need to work with the collections owners to get those fragments moved over 15:33:31 I could be severly underestimating the diligence of all our collection owners 15:33:53 heh, probably not, but they probably haven't thought of it 15:34:23 yes, or are/were busy with other things 15:34:27 the PRs for those changes presumably met the documentation requirements at the time 15:34:32 (like getting sanity tests to pass for all the deprecation changes ;) ) 15:34:33 ok so is the action then to again, contact collection owners and ask them to move their 2.10 porting guide entries into changelog fragments and point them to felixfontein's docs on that? 15:34:43 yes, I think so 15:34:51 yes 15:34:56 if we're feeling nice, we could open a few pairs of sample PRs 15:35:24 #action samccann gundalow contact collection owners to ask them to move their 2.10 porting guide entries into changelog fragments and point them to felixfontein's docs on the correct categories 15:35:37 \o/ 15:36:14 do we want a 2 min update on the docs pipeline? or openfloor? 15:36:28 abadger1999: are you feeling up to a quick update? 15:36:40 PRs for reference of moving fragments / porting guide entries: https://github.com/ansible-collections/community.general/pull/156 https://github.com/ansible-collections/community.general/pull/512 15:37:04 nice! 15:37:21 #info PRs for reference of moving fragments / porting guide entries: https://github.com/ansible-collections/community.general/pull/156 https://github.com/ansible-collections/community.general/pull/512 15:37:48 I started updating the antsibull PR for deprecation-by-date and collection name, so hopefully soon the docs pipeline will support that: https://github.com/ansible-community/antsibull/pull/62 15:38:16 and I created a gist with all collected information on how deprecation now works: https://gist.github.com/felixfontein/06995539f9fc7b06150ab3fe5d80c14e 15:38:35 I plan to post it to https://github.com/ansible-collections/overview/issues/45 soon 15:39:00 w00t! 15:39:08 #topic docs pipeline 15:39:18 Let's see.... 15:39:25 #info antsibull PR for deprecation-by-date and collection name, so hopefully soon the docs pipeline will support that: https://github.com/ansible-community/antsibull/pull/62 15:39:34 I usually on it some over the weekend so it's frsh in my mind what got done in the past week. 15:39:35 #info gist with all collected information on how deprecation now works: https://gist.github.com/felixfontein/06995539f9fc7b06150ab3fe5d80c14e 15:40:10 felixfontein: is it worth mentioning the format for ``? 15:40:37 short-descriptions were ixed 15:40:47 *fixed 15:40:53 do we require `YYYY-MM-DD`? 15:41:00 acozine: good idea. it's ISO-whatever, I always forget the whatever part ;) 15:41:10 ISOThingummy 15:41:43 acozine: yep, we require YYYY-MM-DD. that's iso-whatever ;) 15:41:58 the sanity tests will scream at you if you use an invalid date 15:42:08 good for them 15:42:23 normalize your data, people! 15:42:53 no more random date entries ;) 15:43:21 also version numbers are now linted (i.e. forced to be semver format for collections), which I think makes everything more consistent 15:43:35 abadger1999: hooray for fixed short descriptions! 15:43:56 I have two PRs in progress right now: fixing linking between modules ( https://github.com/ansible-community/antsibull/issues/52 https://github.com/ansible-community/antsibull/pull/92 ). I need to update a module in a collection to use FQCN so that I can test that it works. 15:44:02 * samccann feels like there's a whole lot of docs we're missing on these details 15:44:19 The other PR I'm working on is to add config file/logging. 15:44:27 * acozine agrees with samccann 15:44:41 abadger1999 : I think the supported network collection has updated to FQCN. I'll try and find you an example to play w/ 15:44:58 abadger1999: what can we do to help (other than let you get some sleep)? 15:45:00 community.crypto is also using FQCNs I think 15:45:01 #action samccann to find collection that is already using FQCN in the module docs and pass to abadger1999 15:45:09 heh ok nevermind :-) 15:45:09 community.general and community.network only use it for new plugins/modules 15:48:28 should we do openfloor and wrap things up? 15:48:30 am I looking at the right thing? 15:48:31 https://github.com/ansible-collections/community.crypto/blob/master/plugins/modules/openssh_keypair.py#L13 15:48:35 I don't see an FQCN there 15:48:56 here - https://github.com/ansible-collections/community.crypto/blob/master/plugins/modules/openssh_keypair.py#L97 15:48:59 in the examples 15:49:41 ahhhh, okay thanks samccann 15:50:08 I was thinking of the "incoming" side, I guess - not very logical of me 15:50:25 also using FQCN in https://github.com/ansible-collections/arista.eos 15:50:43 all right, we're 20 minutes over 15:50:45 docs are fun! 15:50:53 #info FQCN used in https://github.com/ansible-collections/arista.eos and https://github.com/ansible-collections/community.crypto 15:51:11 the name in DOCUMENTATION should not be FQCN 15:51:22 @acozine 15:51:26 felixfontein: yep, I was just being muzzy-headed 15:51:44 there was a discussion about that during the last project meeting (last thursday) 15:51:50 * acozine needs more caffeine 15:52:11 yes . . . I remember 15:52:18 * acozine starts having flashbacks 15:53:01 samccann, acozine: thanks :-) 15:53:43 quick open floor, and next week we really will get to the question of whether we want a sample collection in the ansible/ansible docs 15:53:49 #topic open floor 15:54:04 calling everyone who lurks on this channel 15:54:08 now is your chance! 15:54:19 all questions are smart questions 15:54:30 (Oh, I'll need FQCN used in an `M()` or `seealso: { module: }` in the DOCUMENTATION to test this change.) 15:54:48 * abadger1999 looking through arista and community .crypto for those now. 15:56:04 abadger1999: I guess that's currently missing in c.c 15:56:25 felixfontein: okay. I'll make a PR to add them. 15:56:29 I'll look for that as well in the other network collections 15:57:56 abadger1999: thanks! 15:58:38 as always, agenda items welcome 15:58:49 add them to the bottom of https://github.com/ansible/community/issues/521 at any time, meetings are on Tuesdays 15:59:29 have we done it for this week? 16:00:00 thanks abadger1999 felixfontein gundalow samccann 16:00:18 thanks everyone! :) 16:00:26 #endmeeting