15:00:50 #startmeeting Docs Working Group aka DaWGs 15:00:50 Meeting started Tue May 11 15:00:50 2021 UTC. 15:00:50 This meeting is logged and archived in a public location. 15:00:50 The chair is acozine. Information about MeetBot at http://wiki.debian.org/MeetBot. 15:00:50 Useful Commands: #action #agreed #halp #info #idea #link #topic. 15:00:50 The meeting name has been set to 'docs_working_group_aka_dawgs' 15:00:55 #topic opening chatter 15:00:57 who's around? 15:01:49 o/ 15:01:57 abadger1999: dericcrago dmsimard gundalow aminvakil briantist cyberpear felixfontein kindlehl madonius mrproper tremble you folks talking docs today? 15:01:59 #chair samccann 15:01:59 Current chairs: acozine samccann 15:02:06 * dericcrago waves 15:02:18 * tremble will lurk as usual, but have a conflicting meeting 15:02:32 #chair dericcrago 15:02:32 Current chairs: acozine dericcrago samccann 15:02:40 Bom día! 15:02:41 * cyberpear listens in 15:02:48 tremble: welcome, we see you lurking there! 15:02:52 #chair abadger1999 cyberpear 15:02:52 Current chairs: abadger1999 acozine cyberpear dericcrago samccann 15:03:01 dobry den abadger1999 15:03:26 :-) 15:03:59 official agenda https://github.com/ansible/community/issues/579#issuecomment-832143032, but as usual we have some curveballs 15:04:23 hi! I'm only partially around, but feel free to furniturize me :) 15:04:23 nothing scary or anything, just stuff that didn't make it onto the agenda in time 15:04:32 heh 15:04:35 #chair felixfontein 15:04:35 Current chairs: abadger1999 acozine cyberpear dericcrago felixfontein samccann 15:04:54 * gundalow waves 15:05:03 * acozine should add a "three-legged stool" option for folks who are only partially here 15:05:05 #chair gundalow 15:05:05 Current chairs: abadger1999 acozine cyberpear dericcrago felixfontein gundalow samccann 15:05:21 * gundalow sits 15:05:43 * acozine imagines a nice comfy armchair under gundalow 15:06:33 starting to sound like the ancient text-based games in the dim dawn of the internet 15:06:39 heh 15:06:52 * samccann opens the chest with the key 15:07:19 "you don't have the right key, you silly elf" <= from acozine's favorite game of that era 15:07:41 haaahaha 15:07:56 #topic #topic copyright notices 15:07:59 heh 15:08:07 I need remedial IRC training 15:08:18 #undo 15:08:18 Removing item from minutes: 15:08:27 #topic copyright notices 15:08:30 thanks gundalow 15:08:40 everyone's favorite topic 15:08:46 I think the bot ignores it if there's a space at the beginning 15:08:51 #topic copyright notices 15:09:06 fortunately this one's fairly simple and easy 15:09:06 felixfontein: thanks, was wondering why the channel topic didn't change 15:09:17 https://github.com/ansible/ansible/pull/74643 15:10:10 we're proposing changing the copyright on the docs.ansible.com site in line with https://pagure.io/fedora-websites/issue/1078#comment-731193 15:10:33 given the number of contributions we get to the documentation, I think this is a great idea 15:10:43 +1 15:10:50 and it removes the date so.. win win on not needing to fix it EVER AGAIN! 15:10:53 so I kind of wanted to celebrate it here in DaWGs 15:11:00 LGTM 15:11:05 * samccann pulls party hat out of chest 15:12:59 note that this does not invalidate separate copyright notices on individual modules and their documentation 15:14:17 #info updating copyright on docs.ansible.com to drop year/date and credit `Ansible project contributors` see https://github.com/ansible/ansible/pull/74643/files 15:14:28 okay, I'm gonna merge it! 15:14:48 :+1: 15:15:14 #topic update on traffic to existing Scenario Guide TOCs 15:15:20 samccann: take it away! 15:15:41 Ok so we wanted to see how much use folks got from things like https://docs.ansible.com/ansible/latest/scenario_guides/cloud_guides.html 15:16:45 #info https://docs.ansible.com/ansible/latest/scenario_guides/cloud_guides.html gets 1.2k visitors a month. That is 0.2% of all docs traffic 15:17:05 #info and 6% of all scenario guide traffic 15:17:28 (425K visits a month overall) 15:17:34 that's a higher percentage overall than i expected 15:17:44 really? 0.2% is high? 15:17:57 well, when you consider how much traffic goes to module docs 15:18:05 oh, 0.2, not 2.0 15:18:10 I take that back 15:18:13 I thought it was two percent 15:18:13 yeah 15:18:26 okay, those pages can go 15:18:27 much less than 1% :-) 15:18:56 do we vote and then mark it agreed? 15:19:43 VOTE: as we move the Scenario Guides to collections, we will remove the TOC pages for type ("Cloud Scenario Guides" and similar) 15:19:46 +1 15:19:55 #chair 15:19:55 Current chairs: abadger1999 acozine cyberpear dericcrago felixfontein gundalow samccann 15:20:08 oh wai 15:20:09 wait 15:20:16 wait? 15:20:26 do we need at least one stub page to say 'all scenario guides have moved to the collection index? 15:20:42 so someone looking at the left-hand nav can tell what happened? 15:20:44 +1 for leaving stub page 15:21:07 I think we should add an index page at docs/docsite/rst/scenario_guides/index.html (which currently does not exist) 15:21:11 so just one stub page. Call it 'Scenario Guides' and say 'go find your collection 15:21:29 yeah that would work 15:21:36 currently we have https://docs.ansible.com/ansible/latest/scenario_guides/guides.html 15:21:38 +1 for leaving one stub page 15:22:15 we could keep that page, and/or add an `index.html` page so folks won't hit this: 15:22:19 IMO we should also replace the existing guides with links to their new place 15:22:26 so that existing links to them do not break 15:22:30 https://docs.ansible.com/ansible/latest/scenario_guides/ 15:22:53 so we could do that with redirects (old guide to new place) 15:23:02 felixfontein: so, one stub page per guide? 15:23:14 or one per category? 15:23:16 or both? 15:23:19 do we stub it or do we do redirects per guide? 15:23:24 acozine: I would do that, i.e. one stub page per guide 15:23:34 or adding HTTP redirects, whatever is easier 15:23:48 It would be nice if https://docs.ansible.com/ansible/latest/scenario_guides/ had links to the new pages (intersphinx?) 15:23:59 and/or server side redirects 15:24:10 IIRC search engines like Google will behave better with redirects than stubs 15:24:21 I have a slight preference for stubs, only because we can track traffic to them - we can't track usage of the redirects (or at least I don't know how to do it) 15:24:30 my quick count says around 20 or so redirects 15:24:44 tremble: yes, search engines prefer redirects 15:24:59 acozine - you thinking we track traffic to the stubs and then eventually we can remove them? 15:25:04 acozine, redirects should show up in the web server logs 15:25:06 that was my thinking 15:25:26 tremble: unfortunately we do not have access to the web server logs 15:25:29 tremble - we can't see the web server logs w/o begging someone elses time 15:25:37 :( 15:25:38 stub pages inform the user to update their links 15:25:41 so we're flying blind 15:25:41 we can see web analytics easy peasy 15:26:07 abadger1999 good point. 15:27:27 so if we had a stub, will google just keep serving up the stub? 15:27:39 or will it learn people are hopping from the stub immediately to the new location? 15:28:05 I would hope google would also be looking at the new content and updating based on it 15:28:08 and could we solve this w/ a robots file? 15:28:27 a robots.txt would help 15:28:48 (I mean, adding these pages to our robots.txt) 15:29:42 I guess we could try a phased approach 15:29:43 we don't currently have a robots.txt afaik, but maybe stubs are a good place to start one? 15:31:09 ah, you're right, I thought we added one when we added the canonical URLs, but apparently not 15:31:16 cyb-clock sez we are 30 min into the meeting and 16 min into the current topic 15:31:20 heh, thanks 15:31:41 ok how about this for a vote option 15:32:33 VOTE: stub out individual scenario guides to point to their new locations as they are moved. Add the stubs to a robots.txt file on the server so google ignores them 15:32:57 +1 15:33:10 +1 15:33:13 +1 15:33:16 #chair 15:33:16 Current chairs: abadger1999 acozine cyberpear dericcrago felixfontein gundalow samccann 15:33:46 we might also be able to add individual canonical URLs to some pages . . . not sure how/if that would work off the top of my head, though 15:34:49 we don't currently have that level of control 15:35:02 the theme only allows for one cannonical URL to RULE THEM ALL so to speak. 15:35:44 so we have 3 +1s and silence. Do we call that an agreed? :-) 15:36:57 I don't really know how to best SEO but that plan sounds reasonable to me +1 15:37:01 +1 15:37:07 (sorry for the delay) 15:37:12 heh thanks 15:37:41 we can always put in redirects later if we get a ton of complaints or traffic to those pages never dries up 15:37:51 ok 5 +1, 2 silence. 15:38:06 #agreed stub out individual scenario guides to point to their new locations as they are moved. Add the stubs to a robots.txt file on the server so google ignores them 15:39:19 #topic updates on long-running topics 15:39:31 oh, I should have asked first . . . . 15:39:50 anything else on scenario guides TOCs? 15:40:00 not from me 15:40:31 okay 15:40:34 thanks samccann! 15:41:39 update on Scenario Guides more generally 15:41:58 I opened https://github.com/ansible-collections/amazon.aws/pull/362/files - that's the easy (or easier) part of the move 15:41:59 Breadcrumbs: I tested a few builds with the old antsibull and they succeeded. 15:42:08 abadger1999: ooh, awesome! 15:42:27 (I'm going to merge a PR to antsibull to re-enable and then push a new antsibull release) 15:42:42 can you post a link so we can ooh and ahh over the breadcrumbs? 15:43:05 acozine: I guess you need to adjust the labels in that PR, otherwise antsibull won't like it ;) 15:43:18 abadger1999: great news! :) 15:43:32 woot! 15:43:39 ooh, found it: http://docs.testing.ansible.com/ansible/2.10/collections/amazon/aws/index.html#plugins-in-amazon-aws 15:44:19 this is really nice: http://docs.testing.ansible.com/ansible/2.10/collections/community/index.html 15:44:23 #info - breadcrumbs testing seems to be good. abadger to release and updated antsibull that re-enables it 15:44:46 felixfontein: the labels? 15:45:09 acozine: at least for my WIP PR, all labels need to have a specific format, otherwise the RST file will not be accepted 15:45:26 ah, not the PR labels 15:46:04 do you mean https://github.com/ansible-collections/amazon.aws/pull/362/files#diff-e4dc40d0d24dff7c19bd996be43864c677997cb37e8c8c0cccf29562e057daf7R135 labels like that? 15:46:05 acozine: see first line of https://raw.githubusercontent.com/felixfontein/community.docker/scenario-guide/docs/docsite/rst/scenario_guide.rst 15:46:08 #info making some progress on testing the move of a scenario guide to a collection. All still WIP 15:46:22 acozine: yes 15:46:29 that makes sense 15:46:33 I'll start there today 15:47:06 we also still need to discuss (and eventually decide) how to include RST files in the collection index 15:47:17 #info the moved guides will need a specific anchor like .. _ansible_collections.community.docker.docsite.scenario_guide: 15:47:38 just as a reminder :-) 15:47:50 that's not needed, but every label must have that form 15:47:54 felixfontein: good point, shall we start that discussion today? 15:48:01 fine for me :) 15:48:13 cybblock sez we have 13 min left 15:48:16 heh 15:48:21 cyb-clock that is 15:48:32 well, let's get at least one thing on the to-do list if we can 15:48:54 #topic options for including rst documentation in the collection index pages 15:49:15 the PR uses an index.yml file like https://github.com/felixfontein/community.docker/blob/scenario-guide/docs/docsite/index.yml or https://github.com/felixfontein/ansible-tools/blob/main/docs/docsite/index.yml to produce something like https://ansible.fontein.de/collections/community/docker/ resp. https://ansible.fontein.de/collections/felixfontein/tools/ 15:49:50 that only allows a very specific way to insert links though. on the other hand it makes sure you can't completely deface the index page or try to break the build :) 15:50:47 heh 15:51:00 well, saving people from themselves is a reasonable goal 15:51:30 is there a TL;DR; on why we aren't using a standard rst index file here? 15:51:35 I'm a little confused though 15:51:48 I think someone (abadger1999?) suggested to allow free-text include of .rst into the index page, or even make the whole index page templatable (but maybe nobody suggested this and I remember it wrong :) ) 15:51:48 the title is set to `Scenario Guide` here: https://github.com/felixfontein/community.docker/blob/scenario-guide/docs/docsite/index.yml#L3 15:51:59 samccann: because one already exists (that is auto-generated) 15:52:17 and that one we don't want to loose. we want to extend it, not replace it. 15:52:34 felixfontein: I like your impleentatio 15:52:37 felixfontein - ah thanks 15:52:37 but the title on the output is `Docker Guide` here https://ansible.fontein.de/collections/community/docker/ 15:52:40 the auto-generated Plugin Index should stay, and the collection index should be reasonable similar for all collections 15:52:55 oohh, I see, `Scenario Guide` is the section header 15:53:22 I did suggest a raw rst include but I think limiting to section headers and pages under those is fine. 15:53:26 * acozine walks through the logic in her head 15:54:02 we can also start with a very limited way to include things, and later loosen it up if we find it is too restricting 15:54:32 we already have a collection-level index.html page - that's the page that lists all the modules and other plugins and the link to additional materials from the `/docs/` folder 15:54:42 And people always like more options better than having options taken away. 15:55:06 so the index.yml defines what those additional materials should be called on the existing index page 15:55:17 yes 15:55:33 #info https://github.com/felixfontein/community.docker/blob/scenario-guide/docs/docsite/index.yml produces https://ansible.fontein.de/collections/community/docker/ 15:55:58 #info we are looking for a way to inject rst into the existing autogenerated collection index page. 15:56:02 I think the example would be clearer if we used a different file name 15:56:23 something like extra-sections.yml ? 15:56:26 #info so the index.yml defines what those additional materials should be called on the existing index page, under that collection. 15:56:45 docs.yml? 15:57:13 yeah I agree anything other than index. extra-sections is good 15:57:43 if you can agree on a name I'll rename it ;) 15:57:59 like `docker_guide.rst` so the yaml file would have `Title: Scenario Guide` and later `toctree: docker_guide` or something, just so it's easy to tell which line is resulting in what output when you compare the YAML to the HTML 15:58:40 if everything is called Scenario Guide, the example is slightly harder to adapt for other collections 15:58:52 I can implement this in the AWS PR 15:58:56 as an example 15:59:24 (right now the code also supports a list of refs with optional titles, but I think we can also remove that in the beginning) 16:00:04 samccann: you're suggesting a different title for the YAML file, right? 16:00:16 acozine: https://github.com/felixfontein/ansible-tools/blob/main/docs/docsite/index.yml is a more extensive example, with result https://ansible.fontein.de/collections/felixfontein/tools/ 16:00:45 it adds three sections for three filter categories, with docs for the filters in these sections 16:00:57 acozine yeah thought extra-sections.yml helped me understand what it's doing 16:01:36 maybe `extra-docs.yml`? 16:02:01 * acozine enters the bike shed and peers at the colors 16:02:04 cyb-clock sez the local church bells are chiming, must be 1 hr into the meeting 16:02:15 ooo extra-docs 16:02:27 let's go with that and step outa that bike shed! 16:02:31 heh 16:02:49 okay, quick vote 16:03:26 Use `extra-docs.yml` as the file that organizes scenario guides and other collection-level documentation additions 16:03:29 +1 16:03:32 +1 16:03:32 +1 16:03:34 #chair 16:03:34 Current chairs: abadger1999 acozine cyberpear dericcrago felixfontein gundalow samccann 16:04:18 heh, the official meeting time is done, everyone went back to work . . . 16:04:21 +1 16:04:23 heh 16:04:31 :D 16:04:34 I'll update the PR later today. 16:04:42 sounds good thanks! 16:04:55 felixfontein: Will it then be ready for code review? 16:05:06 (and merge if I don't find anything to change)? 16:05:08 I'll get the AWS PR into shape today or tomorrow and publish to the test site 16:05:52 abadger1999: I think so 16:06:09 Cool, I'll put reviwing it on my todo list 16:06:11 I'll also remove the additional code for lists of refs, I think list of toctree is enough 16:06:28 yeah sounds good 16:06:36 if it turns out that this is needed it can be re-added later 16:07:28 #agreed use felixfontein's existing PR for collections additional docs from the /docs/ folder, with one small change - name the top-level YAML file `extra-docs.yml` 16:07:57 #action acozine to update AWS collection PR to match (and fix its anchors) 16:08:12 thanks for the code felixfontein! 16:08:25 okay, quick open floor . . . 16:08:29 #topic open floor 16:08:48 all comments, questions, suggestions, ideas, complaints, requests welcome 16:09:02 we are happy to discuss all things docs 16:09:09 PRs that need review 16:09:10 https://github.com/ansible/ansible/pull/74245 16:09:18 I think that should be revrted in devel 16:09:42 did it go into 2.11? 16:09:44 There are two backports opened now 16:09:47 ah 16:09:49 one for 2.11 and one for 2.10 16:10:06 I think the 2.11 backport should be refused and the 2.10 backport should be merged. 16:10:26 so this is the best solution we can manage for 2.10 16:10:46 but we can do better in the fully-collectionized ecosystem? 16:11:03 I don't know that it's the best we can do for 2.10 but I don't think it has the problem that later versions have 16:11:13 ah, okay 16:11:32 abadger1999: why do you make the distinction for 2.10? 16:11:32 Because there is a docsite for ansible 2.10 ( https://docs.ansible.com/ansible/2.10/ ) 16:11:54 ah, you mean a combined one for Ansible and ansible-base 16:12:03 yeah, one that includes the core functionality AND the module/collection docs 16:12:10 i put a do not merge comment on the 2.11 backport for now 16:12:45 what is the right solution to the problem? can we solve it? 16:13:01 fwiw there is also a core 2.10 docsite 16:13:05 in any case, such changes also have to be supported by antsibull-docs, otherwise things break 16:13:51 (that change breaks the HTML documentation for `set_fact` and `user`) 16:13:51 so how do we decide if the original PR needs to be reverted? and how urgent is it? is something broken already? 16:14:06 heh ok that answers the latter question 16:14:16 in case the devel docs are updated regularly, this breaks them :) 16:14:18 it was broken before, and it's broken now in a different way 16:14:31 Yeah, in a worse way, I think. 16:14:50 #info https://github.com/ansible/ansible/pull/74245 breaks html docs for `set_fact` and `user`. We should consider reverting it 16:14:54 the two links in the modules weren't broken before 16:15:03 felixfontein: oh, if it breaks the html docs, then I guess it should not be backported to 2.10 either? 16:15:23 abadger1999: not without adjusting antsibull-docs first to mirror that change 16:15:29 Yeah. 16:16:43 #info https://github.com/ansible/ansible/issues/73995 relates to this problem 16:16:50 acozine: I think the fix needs to be that ansible-doc needs to become aware of what ansible version it's a part of and generate the link using the ansible versioned link. 16:16:50 ok I put a please do not merge comment on both backports 16:17:31 abadger1999 we don't control ansible-doc. Is there some debate from the owner of that on using your suggested approach? 16:17:36 acozine: If the module/plugin is a part of ansible-core, then ansibl-doc could decide to generate the link to either the ansible-core or the ansible url (using the proper version for those) 16:17:51 abadger1999: so something like "check for a pypi package, if one exists, generate a link with that URL base; if no package exists, check for an ansible-core version and generate a link with that URL base instead"? 16:18:03 samccann: The owner of ansible-doc is the one who pushed the PR that breaks things. 16:18:28 and if there's no package version but the destination link is in a collection, punt and point to `latest`? 16:18:33 yes but is he against fixing it in ansible-doc? or this was just the presumed easier approach for now? 16:18:52 acozine: Yeah, that would work. There are other ways to make it work too, but that way will work. 16:19:34 keep in mind ansible-doc has to work within an execution environment as well (and with ansible-navigator, and Automation Hub etc etc) 16:19:49 samccann: All I know is that at the last meeting htis cam up at, where we said we weren't going to merge it without more discussion, he didn't want to do any additional work on it and couldn't see any problems with his approach. 16:19:50 okay, i will try to write up a github issue that summarizes the original problem, the new problem, and some possible solutions 16:20:24 and also -how we go about reverting the existing merged PR 16:20:41 that part is easy - I can open a revert PR and link to that 16:21:12 cyb-clock sez we are 1hr 20 min into the meeting 16:21:14 heh 16:21:25 acozine: https://docs.ansible.com/ansible/devel/collections/ansible/builtin/set_fact_module.html 16:21:25 thanks 16:21:38 There's a link to the currently broken devel docs page. 16:21:55 thanks 16:22:13 it's broken in the ansible-core page as well. 16:22:24 #info example of broken link - https://docs.ansible.com/ansible/devel/collections/ansible/builtin/set_fact_module.html 16:22:27 #action acozine to summarize the problems with https://github.com/ansible/ansible/pull/74245 in a GitHub issue 16:22:35 The link on that page goes to: https://docs.ansible.com/ansible/devel/collections/ansible/builtin/user_guide/playbooks_variables.html#variable-precedence-where-should-i-put-a-variable which doesn't exist 16:22:40 Err 16:22:41 sorry. 16:22:46 * abadger1999 copies correct link 16:22:56 Oh, that is the correct broken link 16:22:59 ETOOMANYTABS 16:23:02 yep 16:23:16 thanks 16:23:20 no problem 16:23:44 okay, I'll get an issue done and we can discuss again if necessary next week 16:23:56 cool thanks 16:24:02 other open floor items? 16:25:13 hearing none, that's it for this week 16:25:34 thanks abadger1999 cyberpear dericcrago felixfontein gundalow samccann 16:25:44 #endmeeting