15:00:35 <samccann> #startmeeting Documentation Working Group aka DaWGs
15:00:35 <zodbot> Meeting started Tue Aug  9 15:00:35 2022 UTC.
15:00:35 <zodbot> This meeting is logged and archived in a public location.
15:00:35 <zodbot> The chair is samccann. Information about MeetBot at https://fedoraproject.org/wiki/Zodbot#Meeting_Functions.
15:00:35 <zodbot> Useful Commands: #action #agreed #halp #info #idea #link #topic.
15:00:35 <zodbot> The meeting name has been set to 'documentation_working_group_aka_dawgs'
15:00:46 <acozine> o/
15:00:46 <samccann> #topic opening chatter
15:00:53 <samccann> #chair acozine
15:00:53 <zodbot> Current chairs: acozine samccann
15:00:54 <DonNaro[m]> o/
15:00:59 <DonNaro[m]> hiya
15:01:04 <samccann> #chair Don Naro
15:01:04 <zodbot> Current chairs: Don Naro acozine samccann
15:01:07 <samccann> weclome!
15:01:08 <acozine> hey Don Naro welcome back
15:01:08 <samccann> @room Meeting time! Who is here to talk the docs?
15:01:12 <DonNaro[m]> only half here as I'm double booked again
15:01:29 <DonNaro[m]> thanks acozine !
15:01:29 <samccann> briantist: - around to chat docs today
15:01:42 <briantist> sorry I have to miss today's
15:01:42 <tremble> Lurking, with no double-booking for once
15:01:56 <briantist> might pop in if possible
15:01:57 <samccann> #chair tremble
15:01:57 <zodbot> Current chairs: Don Naro acozine samccann tremble
15:02:02 <samccann> Welcome even in lurk mode!
15:02:08 <samccann> Okay thanks briantist
15:02:28 <samccann> Raise your ascii hand (o/) to say hi or any other way you want to let us know you are here. And Welcome to any new folks!
15:03:17 <samccann> Official agenda is at https://github.com/ansible/community/issues/643#issuecomment-1202926085
15:04:19 <samccann> #topic Documentation updates
15:04:33 <samccann> #info PR to set the managed node requirements needs tech review - https://github.com/ansible/ansible/pull/78468
15:04:46 <samccann> Anyone inclined and with the knowledge - ^^
15:06:34 <samccann> I'll probably stage it to be sure about the table. Looks good but I haven't done tables like that much
15:07:52 <samccann> #info User guide is being split into multiple guides. See https://docs.ansible.com/ansible/devel/index.html for current status. More to come.
15:08:04 <samccann> Dunno if you have anything to add Don Naro
15:08:18 <acozine> I have a concern about the managed node PR
15:09:02 <samccann> go for it acozine ... or add it in comments? I haven't much looked at it yet other than to say I need a techie to review ;-)
15:09:05 <DonNaro[m]> not a lot tbh. I'm going to try and get to the inventory content this week. and maybe a separate PR for the BSD stuff.
15:09:10 <acozine> should we mention that some devices can be managed even if they don't have Python installed? Network devices, for example.
15:09:23 <acozine> yeah, I can put a comment on the PR itself
15:09:32 <samccann> acozine: oh yeah that sounds important to add
15:09:49 <samccann> thanks!
15:11:47 <tremble> Do Network device tasks need to explicitly be run on 'local' ?
15:12:08 <acozine> tremble: yes
15:12:38 <samccann> can you explain that acozine ?
15:13:02 <samccann> I'm thinking most connections are set to local but maybe I'm misinterpreting the question
15:13:16 <samccann> like thiis - https://docs.ansible.com/ansible/latest/network/getting_started/first_playbook.html#create-and-run-your-first-network-ansible-playbook
15:13:31 <samccann> sorry are NOT set to local.. doh
15:13:50 <acozine> network automation typically interacts with the network device's API rather than running a python script on the managed node
15:14:19 <samccann> yep
15:14:20 <acozine> so the `connection` is not called `local` but it is very similar
15:14:46 <acozine> in other words, it's not connecting over SSH, copying a python script to the remote node, and then executing there
15:15:23 <acozine> https://docs.ansible.com/ansible/latest/network/getting_started/network_differences.html#execution-on-the-control-node
15:16:00 <acozine> so I guess I mis-spoke when I said you set the connection explicitly to `local`
15:16:26 <acozine> but you must explicitly set the connection type, you cannot use the default SSH connection
15:16:33 <samccann> ok thanks
15:18:00 <acozine> anyway, I'm adding a comment to the PR
15:18:00 <samccann> cool thanks!
15:18:08 <samccann> #info - if you need an editor to review docs PRs or do light editing (edit on github) we have a team of community writers willing to help. See https://github.com/orgs/ansible-community/projects/3/views/1?sortedBy%5Bdirection%5D=asc&sortedBy%5BcolumnId%5D=Status and ping us here if you need access to add your PRs/easyfix issues to that board.
15:18:30 <samccann> #info always looking for help on the backlog - issues - https://github.com/ansible/ansible/issues?q=is%3Aopen+is%3Aissue+label%3Adocs and PRs - https://github.com/ansible/ansible/pulls?q=is%3Aopen+is%3Apr+label%3Adocs
15:19:02 <samccann> #topic doctools
15:19:10 <samccann> #info Switching boolean yes/no vs true/false based on https://github.com/ansible-community/community-topics/issues/116.
15:19:38 <samccann> A lot of ^^ is coding that I think felix is already got a PR somewheres for. Once that's done and we redo the docs, we can see how much has to be manually edited
15:20:47 <samccann> tho I don't plan on going into 90+ collections and editing any comments/examples that don't follow suit. Mostly talking about the guides for manual edits to use  `true/false`
15:22:40 <samccann> #info need to update docs requirements before end of core freeze (aka by early Sept).
15:23:07 <samccann> We have updates to `antsibull-docs` for sure, but the other dependencies have progressed since our last update so I'll be testing those out soon
15:24:33 <samccann> I'm not sure if `antsibull-docs` is stuck between a rock and a side-car docs hardplace or not.  That feature is supposed to be part of 2.14 but last I heard it has some work to do. If it slips to 2.15 for example, we'd have to pull that out of `antsibull-docs`
15:24:42 <samccann> and by we, I mean felix :-)
15:24:48 * samccann needs to stop w/ the royal we
15:24:57 <acozine> so the September freeze is for core 2.14?
15:25:03 <samccann> yep
15:25:35 <samccann> so my plan is to get our updated requirements ready a couple of weeks before that. But that may not jive w/ sidecar docs deadlines etc
15:26:12 <samccann> So we could update everything else 'now-ish' and then again whenever that resolves. The other dependencies, other than the theme, are external packages
15:26:42 <samccann> the gotcha is that whenever we update, core has to regenerate test containers. So I'm trying to only do it once a cycle so to speak.
15:27:05 <acozine> that makes sense
15:28:35 <samccann> #topic Open Floor
15:28:43 <samccann> That's about all I had. Anyone else have docs topics to talk about today?
15:29:35 <samccann> I sorta kinda volunteered Don Naro to take a look at our growing # of conf.py files... though that won't happen overnight for sure
15:30:14 <samccann> we have 3 already, and I have PR adding a fourth to get the japanese version switcher working... Felix mentioned maybe a jinja2 template could create them for us based on the Makefile command etc
15:30:17 <acozine> conf.py files?
15:30:21 <acozine> ah, for that
15:30:26 <samccann> yep
15:30:58 <samccann> For others - these control how sphinx builds our docs. We have 4 things going on now:
15:30:58 <samccann> 1 - core
15:30:59 <samccann> 2 - Ansible (the package)
15:31:06 <samccann> 3 - creating..erm.. some kinda files to feed into translation
15:31:20 <samccann> 4 (the new one) japanese translated docs with functional version switcher
15:31:48 <samccann> right now it's all done with separate conf.py files and symlinks at make time.
15:32:10 <samccann> but 90% of the content of each is identical. so it's getting harder and harder to keep them in sync.
15:33:48 <acozine> it would be cool to automate them from a template
15:33:51 <acozine> create them on the fly as part of the docs build
15:34:18 <acozine> I suppose that might introduce other complications
15:34:45 <samccann> something specific you have in mind?
15:35:04 <acozine> no, just a nagging sense that there was a reason we did what we did
15:35:20 <acozine> it's totally possible that the "reason" was we were in a hurry
15:35:25 <samccann> yeah, because I didn't know any better?  :-)
15:35:34 <samccann> Anyway, anything else before we close the meeting?
15:37:45 <samccann> #endmeeting