14:32:12 <acozine> #startmeeting Docs Working Group aka DaWGs
14:32:12 <zodbot> Meeting started Tue Aug  4 14:32:12 2020 UTC.
14:32:12 <zodbot> This meeting is logged and archived in a public location.
14:32:12 <zodbot> The chair is acozine. Information about MeetBot at http://wiki.debian.org/MeetBot.
14:32:12 <zodbot> Useful Commands: #action #agreed #halp #info #idea #link #topic.
14:32:12 <zodbot> The meeting name has been set to 'docs_working_group_aka_dawgs'
14:32:16 <acozine> #topic opening chatter
14:32:22 <acozine> #chair samccann
14:32:22 <zodbot> Current chairs: acozine samccann
14:32:45 <acozine> who's DaWG-ing today?
14:33:40 <acozine> baptistemm felixfontein gundalow andersson007_ briantist cbudz cyberpear jhawkesworth Jmainguy madonius persysted Pilou shaps tadeboro Tas-sos tremble you folks around?
14:33:43 <felixfontein> hey!
14:33:52 <acozine> hey felixfontein!
14:33:54 <felixfontein> DaWG-ing-s
14:33:55 <acozine> #chair felixfontein
14:33:55 <zodbot> Current chairs: acozine felixfontein samccann
14:34:00 <cbudz> greetings
14:34:03 <gundalow> acozine: I'm here
14:34:08 <acozine> #chair cbudz gundalow
14:34:08 <zodbot> Current chairs: acozine cbudz felixfontein gundalow samccann
14:34:12 <acozine> welcome!
14:34:46 <acozine> today's official agenda: https://github.com/ansible/community/issues/521#issuecomment-665127634
14:34:57 <tadeboro> I am also stalking you all ;)
14:35:17 <acozine> heh, welcome tadeboro
14:35:21 <acozine> #chair tadeboro
14:35:21 <zodbot> Current chairs: acozine cbudz felixfontein gundalow samccann tadeboro
14:36:36 <acozine> we'll get started, but folks are welcome to join at any time!
14:36:52 <acozine> #topic changelogs and porting guides
14:37:03 <felixfontein> there isn't *that* much to update this time
14:37:15 <acozine> I have a quick update on changelogs
14:37:24 <baptistemm> hello
14:37:30 <felixfontein> first thing: I've been trying to get rid of the collections porting guide entries from the Ansible porting guide (fixed part): https://github.com/ansible-community/ansible-build-data/pull/23
14:37:35 <acozine> welcome baptistemm!
14:37:38 <acozine> #chair baptistemm
14:37:38 <zodbot> Current chairs: acozine baptistemm cbudz felixfontein gundalow samccann tadeboro
14:38:05 <acozine> felixfontein: nice!
14:38:06 <felixfontein> also I did some work on automatically inserting release summaries for new releases: https://github.com/ansible-community/antsibull/pull/164
14:38:23 <felixfontein> this is the result: https://github.com/ansible-community/ansible-build-data/pull/25/files
14:38:43 <felixfontein> that's my news
14:38:52 <felixfontein> (sorry for interrupting you acozine)
14:39:08 <acozine> felixfontein: I think we interrupted each other, maybe
14:39:28 <felixfontein> btw, is it just me, or is the .rst preview on github broken for everyone?
14:39:33 <acozine> thank you for the follow-through on those entries
14:39:45 <samccann> #info removing collections porting guide entries from ansible-base porting guide - https://github.com/ansible-community/ansible-build-data/pull/23
14:40:02 <samccann> #inserting release summaries for new releases https://github.com/ansible-community/antsibull/pull/164
14:40:08 <samccann> AHAHAH
14:40:22 <samccann> #info inserting release summaries for new releases https://github.com/ansible-community/antsibull/pull/164
14:40:44 <acozine> felixfontein: where are you seeing .rst previews broken?
14:40:56 <felixfontein> (there are a handful entries left; community.grafana has no changelog we can automatically include, and I didn't check the 3rd party collections)
14:41:25 <felixfontein> when clicking on "rich diff" in https://github.com/ansible-community/ansible-build-data/pull/25/files?short_path=34e94ff#diff-34e94ff06c034caba36782cfa3bd97ea
14:41:33 <felixfontein> https://github.com/ansible-community/ansible-build-data/blob/b9c8acdc6b32ca2e4866e4784e9f2eb68b1a1042/2.10/CHANGELOG-v2.10.rst works again
14:41:45 <felixfontein> (didn't work for me yesterday)
14:42:33 <samccann> #info  community.grafana has no changelog we can automatically include, and TBD on the state of the 3rd party collections
14:42:33 <acozine> huh, yeah, that first link shows "Sorry, we're unable to render a diff" for me as well
14:42:58 <acozine> weird
14:43:10 <gundalow> felixfontein: yup, I've seen some issues with RST diffs, not worked out the pattern yet
14:43:38 <acozine> the rst preview usually drives me crazy, because I prefer to see the rst source, but I admit it can be useful at times . . . and not having any diff at all is maddening
14:44:06 <felixfontein> yesterday evening neither of them worked, and diff was the first to click on right now ;)
14:44:55 <acozine> well, fingers crossed (or thumbs held) that it gets fixed soon
14:45:06 <felixfontein> btw, gundalow, is https://github.com/ansible-community/ansible-build-data/pull/25/files what you wanted (and thus also https://github.com/ansible-community/antsibull/pull/164)?
14:45:46 <acozine> my update on changelogs is: I got the new categories backported to 2.9 and 2.8 (see https://github.com/ansible/ansible/pull/71072 and https://github.com/ansible/ansible/pull/71071)
14:46:24 <felixfontein> cool!
14:46:46 <acozine> so now we can backport `security_fix` changes to all maintained versions
14:47:26 <samccann> #info we can now backport `security_fix` changes to all maintained versions (new categories backported to 2.9 and 2.8)
14:47:32 <gundalow> felixfontein: yup, porting guide links there is good, thank you
14:49:07 <acozine> felixfontein: this is nitpicky, but i'd make the text of those links to the Porting Guide section say `Porting Guides`, or else link them to specific/individual Porting Guide 2.x pages
14:49:25 <acozine> https://github.com/ansible-community/ansible-build-data/pull/25/files#diff-34e94ff06c034caba36782cfa3bd97eaR23
14:50:31 <felixfontein> acozine: fine for me. I was looking at the 2.9 changelog, which says "Porting Guide", but I now see it links to the list of porting guides (in devel)
14:51:02 <felixfontein> ah. that's the same as I did :)
14:51:12 <acozine> heh
14:51:12 <felixfontein> acozine: https://github.com/ansible/ansible/blob/stable-2.9/changelogs/CHANGELOG-v2.9.rst#v2-9-11 does exactly the same
14:51:51 <acozine> hmm, okay, we should either fix them all, or leave them all like that, i guess
14:52:06 <acozine> I vote we leave them all
14:52:13 <samccann> +1
14:52:17 <felixfontein> +1
14:52:19 <acozine> if we get bored in future (!!!) we can get all nitpicky
14:52:21 <felixfontein> we can still change them in the future
14:52:23 <felixfontein> hehe :)
14:52:58 * gundalow has to drop. I'll read scroll back later
14:53:02 <acozine> overall, the changelogs and porting guides are looking great!
14:53:16 * acozine waves to gundalow
14:54:30 <acozine> anything else on changelogs/porting guides today?
14:54:55 <felixfontein> acozine: thanks!
14:54:57 <felixfontein> bye gundalow!
14:54:59 <felixfontein> not from my side
14:56:42 <acozine> the next topic in the agenda is the publication pipeline, but maybe we can hold off on that for a while and see if our West Coast colleague (whom I will not mention by name because i don't want to ping his phone or other devices) joins us before the meeting ends
14:57:00 <felixfontein> :)
14:57:11 <felixfontein> let's let him sleep
14:57:12 <samccann> heh
14:57:30 <acozine> #topic banners and other docsite formatting
14:57:47 <acozine> I have a question for the DaWGs hivemind
14:58:13 * baptistemm is not a bee
14:58:26 <acozine> heh, but your name even starts with B!
14:58:32 <felixfontein> lol
14:58:35 <baptistemm> Dam'
14:59:02 <samccann> woopsie
14:59:21 <acozine> trying to fix the problem of printing the "you're reading the devel docs" banner on any page with `devel` in the title anywhere, like https://docs.ansible.com/ansible/2.8/dev_guide/developing_modules.html
15:00:06 <felixfontein> I didn't notice on this machine, since I hadn't activated javascript :)
15:00:23 <acozine> heh
15:00:34 <acozine> we came up with https://github.com/ansible/ansible/pull/70849 for the fix
15:00:48 <acozine> merged that, opened backports, and published all versions to the testing site
15:01:20 <acozine> and it worked . . . sort of
15:01:24 <acozine> http://docs.testing.ansible.com/ansible/2.8/dev_guide/developing_modules.html
15:01:46 <acozine> there's no devel banner . . . but the page doesn't look so good in mint green
15:02:39 * acozine thinks she'll use the term "DaWGs packmind" next time
15:02:48 <samccann> heh
15:03:22 <tadeboro> "Looks fine in lynx" is my response when someone complains about horrible color choices in my "designs" ;)
15:03:27 <baptistemm> ah
15:03:47 <samccann> as I recall with baptistemm's earlier banner fixes, it seems like a <div> or something is no longer closed (and thus everything goes green).  I looked at  the good vs not so good versions of that other PR and compared to see what was missing
15:03:54 <samccann> didn't get far enough to find a solution tho
15:04:19 <baptistemm> we also use our own copy of the theme instead of using the one maintained on a separate repo
15:04:20 <acozine> tadeboro: heh, I'm using that
15:04:51 <felixfontein> which PR is producing the incorrect banner?
15:05:12 <acozine> felixfontein: https://github.com/ansible/ansible/pull/71077
15:06:17 <acozine> ohhhh, from that comment, we need to tweak the "you're using an older version" banner too
15:06:25 <acozine> since 2.10 is not an "older version"
15:06:34 <acozine> a separate but related issue
15:06:58 <felixfontein> acozine: is the result visible somewhere?
15:07:30 <acozine> that testing link . . . hang on
15:07:39 <acozine> http://docs.testing.ansible.com/ansible/2.8/dev_guide/developing_modules.html
15:08:09 <samccann> #info banner PR https://github.com/ansible/ansible/pull/71077 produces problem at http://docs.testing.ansible.com/ansible/2.8/dev_guide/developing_modules.html
15:08:33 <samccann> #info banner PR attempting to not show devel banner on pages that have devel in the page title, as above
15:09:07 <felixfontein> ah
15:09:14 <felixfontein> it does that because the JS code crashes
15:09:17 <acozine> it would be great to get baptistemm's https://github.com/ansible/ansible/pull/70778/files working and merged this week too
15:09:23 <felixfontein> "Uncaught TypeError: element is null"
15:09:30 <acozine> oh, fun
15:09:47 <tadeboro> I like it. No fixes needed ;)
15:09:51 <samccann> heh
15:10:02 <acozine> well, given that error, I guess the output could've been a lot worse
15:10:11 <felixfontein> I added a comment (I can't comment on the line that actually needs to be changed)
15:10:21 <acozine> felixfontein: thanks
15:10:42 <felixfontein> I would put the `</div>` into the `document.write()` statement which prints the `<div>`, to avoid such problems
15:11:38 <samccann> #info fix id per command and consider putting  the `</div>` into the `document.write()` statement which prints the `<div>`, to avoid such problems
15:12:36 <acozine> all right, more tweaking and testing today . . . thanks for the pointers!
15:13:36 <baptistemm> can't we render that directly in the RST ?
15:14:09 <samccann> there may be other ways to do the banner. I just found an example and modified it to fit our needs
15:14:17 <felixfontein> baptistemm: parts of it yes (probably the things dependent on the relative path). the things depending on the domain, probably not
15:14:47 <felixfontein> baptistemm: it's not completely obvious though how to get hold of the filename of the currently templated file, at least from the docs I found (haven't tried it)
15:15:23 <felixfontein> though the build would need external input probably
15:15:35 <felixfontein> anyway, the current solution works good enough without changing the build :)
15:16:03 <acozine> speaking of docsite stuff, we turned the broken `Edit on GitHub` links off for the module/plugin docs for now, until we have a way to route those: https://github.com/ansible/ansible/pull/70951 (thanks samccann!)
15:16:49 <tadeboro> When I am dealing with the sphinx, I usually parameterize the documentation generation. This means that I neeed to generate docs for each combination of domains/parameters, but I found it way more maintainable compared to messing around with the javascript.
15:17:04 <samccann> Yeah it's a temporary fix so I didn't close all the existing 'edit on github is broken' issues. So we remember that needs some coding magic to bring it back.
15:17:13 <acozine> tadeboro: can you post an example of the way you do that?
15:18:43 <tadeboro> acozine: It will take me a while since I do not have access to my office computer that contains those files (company is renovating the offices and cutting cables if fun or something).
15:19:01 <acozine> tadeboro: ah, renovations!
15:19:18 <tadeboro> acozine: But will do it ASAP. But things boil down to setting a few html_theme_options in the config and then using them in the templates.
15:19:27 <acozine> if/when you get a chance, it would be great to see that code
15:20:03 <baptistemm> the same for me
15:20:05 <samccann> #action - tadeboro to provide sphinx example for parameterized doc generation (when time permits)
15:20:23 <samccann> not pressure ^^ just want it as a reminder so we can ask again in a couple of weeks
15:20:51 <acozine> thanks samccann for keeping us organized!
15:21:32 <acozine> any other ideas/suggestions/complaints/comments on the docsite formatting/look-and-feel/banners?
15:21:58 <baptistemm> acozine: as I said I con't link the content on the left banner
15:22:11 <baptistemm> s/con/don/
15:22:29 <baptistemm> but this is a huge task to tackle
15:22:30 <acozine> yeah, I'm sure there's a way to make that link work
15:22:40 <acozine> I just don't know what it is yet
15:23:21 <baptistemm> acozine: is there an improvement to use the sphinx theme that is hosted on separatated repo ?
15:23:32 * baptistemm stumbled
15:23:52 <samccann> the improvement would be when we make something work, it will work for anyone using that theme
15:24:13 <samccann> But the drawback is - we'd have to test the improvements out on ...anyone using that theme :-)
15:25:10 <samccann> and we'd probably have to have someone in RH officially 'maintain' that theme since our docs would depend on it.
15:25:32 <acozine> ultimately it would be good to use the "packaged" theme, but it might solve some problems and introduce different/new problems
15:26:15 <felixfontein> is it possible to extend / inherit themes?
15:26:16 <acozine> if we could come up with some way to test the theme regularly, that would be awesome
15:26:28 <abadger1999> samccann: I don't think we're building docs for things shipped in rht anymore.
15:26:30 <felixfontein> so like most things can be moved to a common base theme, and things like the banners could be ansible-only?
15:26:37 <acozine> felixfontein: I'm not sure, I assume you can override certain files locally
15:26:43 <abadger1999> so it's probably okay if it's maintained outside of rht.
15:26:57 <acozine> abadger1999: welcome~
15:27:01 <acozine> #chair abadger1999
15:27:01 <zodbot> Current chairs: abadger1999 acozine baptistemm cbudz felixfontein gundalow samccann tadeboro
15:27:04 <abadger1999> (as long as everyone gets along well ;-)
15:27:12 <tadeboro> Sphinx themes can be extended, but it is not as easy as one would have hoped.
15:27:26 <acozine> tadeboro: that sounds like the voice of experience
15:27:41 <samccann> abadger1999: not sure about that. if docs.ansible.com depends on this reusable theme, we'd have to 'adopt' it wouldn't we? Otherwise community could decide to change the color to purple or something and we'd have no notice
15:27:51 <baptistemm> I don't know how RH patch the docsite for the redhat automation hub
15:28:18 <samccann> baptistemm: that's entirely handled by RH internally.
15:28:39 <acozine> baptistemm: the AH docs don't use sphinx
15:28:44 <abadger1999> samccann: Maybe?  It's similar to what would happen if sphinx or the notfound plugin updated incompatibly, though.
15:28:56 <samccann> abadger1999: true
15:28:57 <abadger1999> So I suppose it's degree of risk.
15:29:09 <felixfontein> does AH also contain ansible docs? (I mean the ansible docs from ansible/ansible)
15:29:18 <samccann> yeah I guess we do just grab these things and hope for the best over  time!
15:29:27 <acozine> felixfontein: no, only module/plugin docs
15:29:29 <tadeboro> felixfontein: AS far as I can tell no.
15:30:04 <felixfontein> ok
15:30:15 <samccann> #info - the reusable sphinx theme would be good to adopt, but we need to figure out a way to test changes so it won't break all the places currently using it
15:30:44 <baptistemm> samccann: can't we render pages produced during PR to a temporary place ?
15:30:57 <acozine> it's the end of our scheduled hour . . . can folks stick around for ten more minutes?
15:31:03 <baptistemm> I seems other RH docs team for openshift doing that
15:31:05 <felixfontein> sure
15:31:09 <samccann> we can yes... I don't know what ansible-lint can do for example. it's hosted somewhere else
15:31:20 <acozine> baptistemm: yes, we can publish any branch to the testing site
15:31:41 <samccann> any of OUR branches. not the stuff up on readthedocs using this reusabl theme
15:31:49 <acozine> true
15:32:12 <baptistemm> but something like http://pr-34353.testing.ansible.com/ would be awesome
15:32:46 <acozine> baptistemm: huh, interesting idea, that would be cool
15:33:06 <felixfontein> should be protected by HTTP basic auth though, IMO, to avoid this being abused to host random stuff
15:33:08 <baptistemm> not sure how to acheive to that
15:33:12 <baptistemm> felixfontein: indeed
15:33:31 <acozine> agreed
15:34:07 <felixfontein> (I'm wondering whether someone already abused a project's CI to mine bitcoin/...?)
15:34:23 <acozine> heh, probably
15:34:41 <baptistemm> felixfontein: ah you thought about someone adding some JS in the PR
15:34:57 <baptistemm> you're too smart to me
15:34:58 <acozine> I don't think we'd want to make that fully automated
15:35:24 <felixfontein> baptistemm: in case of docs PR, more like some binary file (say with malware)
15:35:36 <felixfontein> or a phishing form
15:35:39 <acozine> among other things, we'd quickly have hundreds of sets of the docs on the testing site
15:36:08 <acozine> even if no abuse happened (which it probably would)
15:36:22 <felixfontein> yep
15:37:06 <acozine> #info explore options for publishing individual PR changes to the test site in a way that makes them easy to find, for example `PR2.testing.ansible.com` or similar, with security and cleanup
15:37:14 <tadeboro> We at my company generate docs on MRs that have a specific tag + master branch.
15:37:37 <tadeboro> (We use Gitlab internaly, this is why MRs and not PRs ;)
15:38:02 <acozine> tadeboro: generate the docs to URLs that include the tag?
15:39:16 <acozine> I think we need to focus on the challenges of the 2.10 docs first, though
15:39:29 <samccann> :-)
15:39:52 <acozine> once 2.10 has been released, this stuff would be great to explore!
15:40:00 <acozine> in that spirit . . .
15:40:06 <acozine> #topic docs pipeline update
15:40:13 <acozine> abadger1999: could you do a quick update on pipeline issues?
15:41:15 <abadger1999> Over the past week, I fixed a couple bugs that were causing the pipeline to fail on specific user's platforms.
15:41:48 <acozine> hooray!
15:42:02 <abadger1999> (macos was having trouble building the devel docs; my system was having trouble with virtulenvs for some reason)
15:42:22 <abadger1999> I started work on routing but it didn't get my full attention like I thought.
15:42:34 <abadger1999> I have an outline of how to do it and the dependencies needed.
15:42:47 <abadger1999> But only a skeleton of code so far.
15:43:32 <acozine> any blockers we can help with?
15:43:35 <abadger1999> I haven't encountered anything that I would consider a blocker, though.
15:43:56 <acozine> cool
15:44:25 <abadger1999> It's mostly just a matter of writing code but I suppose there are some questions about how the redirects should be output.
15:44:50 <abadger1999> (Each directory has its own .httpaccess file?  One central file for all redirects?)
15:45:00 <abadger1999> Those may be better to look at once I have a strawman, though.
15:45:24 <acozine> sounds good
15:45:41 <abadger1999> Implement it using one central file and then you all can tell me if it should be done differently ;-)
15:45:53 <acozine> heh
15:46:04 <felixfontein> probably it's best to collect all redirects and have some global redirect writer - that could then be easily changed to output them differently (or even for another HTTP server)
15:46:27 <abadger1999> Since this is likely to need to be run repeatedly, I think  it will end up being a new script in the antsibull package.
15:47:35 <abadger1999> I was thinking of just doing a one-off script a few weeks ago, but I think there's likely to be updates to the ansible-base runtime.yml into the future (or at least pressure to update it and I want to be prepared whichever way that decision ends up falling).
15:47:53 <acozine> that sounds like smart future-proofing
15:48:16 <abadger1999> That's all I have for status for this week :-)
15:48:21 <felixfontein> ah, you are talking about these redirects, not the redirects inside collection docs
15:48:53 <felixfontein> abadger1999: there *will* be updates: https://github.com/ansible/ansible/pull/71081 (probably won't make it into 2.10.0)
15:49:03 <acozine> abadger1999: thanks!
15:49:28 <abadger1999> felixfontein: Since I'm going to implement it inside of antsibull, I'll probably merge that functionality.
15:49:45 <abadger1999> I'm not sure if it will be there immediately, though ;-)
15:49:50 <felixfontein> :+1:
15:50:14 <abadger1999> getting ansible-base's runtime.yml will hit 85% of the redirects so it's the big thing right now.
15:50:35 <felixfontein> yep
15:50:59 <felixfontein> and processing the others needs also new module/plugin listing code
15:51:03 <felixfontein> (for antsibull-docs)
15:52:47 <acozine> anything else on pipeline?
15:53:13 <acozine> #topic open floor
15:53:40 <acozine> all questions, complaints, suggestions, contributions welcome
15:54:32 <samccann> chocolates also welcome :-)
15:54:36 <acozine> as always, anyone can add an item to the official agenda by putting a comment on https://github.com/ansible/community/issues/521
15:54:41 <acozine> samccann: ooh, chocolate
15:55:22 <acozine> we prioritize agenda items from the community, and especially new contributors/participants
15:57:35 <acozine> thanks abadger1999 baptistemm felixfontein samccann tadeboro gundalow cbudz
15:57:57 <abadger1999> Thank you for running the meeting :-)
15:58:08 <acozine> chat on the channel encouraged at all times, next official meeting next Tuesday, August 11
15:58:25 <felixfontein> thanks a lot everyone!
15:58:30 <acozine> #endmeeting