16:01:34 #startmeeting Documentation Working Group aka DaWGs 16:01:34 Meeting started Tue Feb 21 16:01:34 2023 UTC. 16:01:34 This meeting is logged and archived in a public location. 16:01:34 The chair is samccann. Information about MeetBot at https://fedoraproject.org/wiki/Zodbot#Meeting_Functions. 16:01:34 Useful Commands: #action #agreed #halp #info #idea #link #topic. 16:01:34 The meeting name has been set to 'documentation_working_group_aka_dawgs' 16:01:59 @room Meeting time! Who is here to talk the docs? 16:01:59 o/ 16:02:00 * kristianheljas is listening along, likely wont talk much, but would like to catch samccann later on 16:02:02 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! 16:02:05 #chair tremble 16:02:05 Current chairs: samccann tremble 16:02:08 o/ 16:02:25 kristianheljas: cool thanks! 16:02:27 #chair Don Naro 16:02:27 Current chairs: Don Naro samccann tremble 16:02:37 To any newcomers - again, welcome. We chair all attendees as a way of recognizing your time spent here. And it opens it up for people to add to the meeting minutes with commands like #info or #link (to add a link) 16:02:47 General run of the meeting - We go over action items, give docs updates.. maybe have a topic or two, and go over doctooling updates (all the fun stuff behind the scenes that get us docs.ansible.com!) 16:03:29 felixfontein: briantist - around to talk docs today? 16:03:31 o/ 16:03:52 #chair felixfontein 16:03:52 Current chairs: Don Naro felixfontein samccann tremble 16:03:58 welcome welcome everyone! 16:04:27 Agenda is https://github.com/ansible/community/issues/678#issuecomment-1430071104 16:04:38 #topic Action Item updates 16:04:45 #info open -Looking for community maintainer(s) for the sphinx ansible theme 16:05:03 o/ 16:05:06 I'm wondering if we should be requesting this in other channels? I think it was mentioned in the bullhorn once 16:05:11 #chair briantist 16:05:11 Current chairs: Don Naro briantist felixfontein samccann tremble 16:05:14 Welcome! 16:05:45 welcome indeed 16:05:54 are there any thoughts of replacing the theme completely? like getting rid of the current way the top bar is done? 16:06:13 ('replacing' could be 'create a new major version which is very different from the old one') 16:06:23 yeah I put that in the Bullhorn before Fosdem and have done a bit of hacking at it but have been a little sidetracked 16:06:43 I think new major version would be great felixfontein and I'd be interested in contributing to it 16:07:07 felixfontein: interestingly that top bar was 'inherited' by the Ansible.com stuff, but ...wow has that site changed! 16:07:18 So my nickel is we an surely reconsider that part of it 16:07:53 for those following along, we're talking about the black bar at docs.ansible.com. 16:07:55 I'm happy to help if that ugly thing (from a technical POV) doesn't have to stay ;) 16:08:06 AHAHAHA 16:08:07 it's causing problems all over (see the recent bug) 16:08:27 well, most of them are due the way it is implemented 16:09:01 hmm I'm missing 'the recent bug' do you have a link? 16:09:04 I don't see new issues here -https://github.com/ansible-community/sphinx_ansible_theme/issues 16:10:00 https://github.com/ansible-community/sphinx_ansible_theme/issues/84 this one 16:10:32 ah ok 16:10:45 it's caused by hacks to work around the issues introduced by the header bar :) 16:10:56 So there's also a 'ng theme' issue there. So we're definitely willing to change 16:10:59 (and the solution is to add another hack to that list of hacks...) 16:12:34 so in general, we're ever-so-slowly clawing our docsite back for community. So if that black bar is a problem... it can go imo. 16:12:52 As Don has pointed out, we are community docs and most of that bar is: 16:12:58 a - product focused 16:13:04 b- likely woefully outdated 16:13:34 #info one of the drawbacks of current theme is that black header bar at the top. We are open to redesigning the theme to remove/replace and keep it all community-focused 16:14:24 Don Naro: you know the current person working on that theme.. do you feel there would be any pushback if we opened it up for a redesign? 16:14:32 not at all 16:14:57 ok so what's our next action to take on this? There's already an issue for 'ng theme'. 16:15:20 https://github.com/ansible-community/sphinx_ansible_theme/issues/41 16:15:48 maybe it would be nice to decide on what the community needs out of a new theme 16:16:31 new theme will be entirely flash-based, yeah? 16:17:10 I guess the current call for contributors is a bit of a shot in the dark in some ways. maybe we could gather a list of requirements for the theme and then put this into the community team board? 16:18:14 it would definitely help (potential) maintainers to know what the actual requirements are 16:18:14 ok so the question then in my mind - 16:18:30 do we 'fix' what is currently there (even if it means removing the top header) 16:18:42 or do we move on to some future wonderful live is grand theme? 16:19:08 s/live/life/ 16:19:27 the thing is that https://github.com/ansible-community/sphinx_ansible_theme/issues/41 sounds like someone already has a plan, which means that contributing to https://github.com/ansible-community/sphinx_ansible_theme/ in general seems to be discouraged when it will likely be completely replaced anyway 16:19:41 tbh I think it would be nice to try and start from the ground up a little. I hacked around with the current theme but it seems that results in hacks on top of hacks. 16:20:59 ok we can definitely followup with the person who created that issue 16:21:01 I can take an action to discuss this with Sviat and get back to the DaWGs next week 16:21:36 #action Don Naro to follow up with current maintainer of ansible-sphinx-theme on proposal to replace it with something else 16:21:57 Brings up the question tho - if he is open to that, do we have people who will work to create a new theme from the ground up? 16:24:18 well I'm certainly willing. I think the theme is important and we've finally got most of the projects in the Ansible ecosystem using it. so hopefully it's something we can do with help from others. maybe we just need to get the requirements in order and identify pieces of actual work. 16:25:42 right now it's one of those "how long is a piece of string?" scenarios where raising your hand might get you on the hook for a lot more than you bargained for. but if we can parcel things out into smaller tasks then it might be a better way to get contributors. 16:26:49 ok Don - can you open an issue on the community-team repo to 'evaluate creating a new theme for ansible docs' 16:27:13 We can use that to track ideas, and if Sviat is interested in helping etc 16:27:42 will do 16:27:55 #info open samccann to create a list of 'docs stuff that needs updating for new release' to catch things like roadmap updates early on. 16:28:01 #info open - all - clone the jinja2-docsite repo and show us how you'd like to improve docs.ansible.com https://github.com/ansible/jinja-docsite 16:28:16 So that's the way we'll prototype a new docsite ^^ 16:28:36 #info closed samccann to update docs requirements versions before Feb 20 16:29:35 so the requirements are updated. Matt will at some point update CI containers. This is the only big lift to requirements we'll do for 2.15... with the caveat that we might need to update antsibull-docs to fix things. I'd like to refrain from changing antsibull-docs other than if something is broken, once the core branch pull happens 16:29:46 I wouldn't mind helping with a new theme, though I'm not sure I want to be the only person working on that :) 16:29:55 (sorry got a bit side-tracked) 16:30:42 oh wow... core branch pull is a month away.. not sure how I got that confused lol. Thought it was start of March... 16:30:57 so...we have a bit more time if antsibull-docs features are still in the works 16:31:19 Thanks felixfontein yeah would want to have a few people helping for sure 16:31:46 what is core branch pull? 16:32:08 when the core team branches stable-2.15 16:32:18 https://docs.ansible.com/ansible/devel/roadmap/ROADMAP_2_15.html#release-phase 16:32:21 Ah 🙂 16:32:24 Thanks! 16:33:01 basically, someone on the core team has to update a batch of CI test containers whenever we update our docs requirements (a point that will be brought up in the next discussion). So we try to lessen the pain on them by batching all before the branch pull happens. 16:33:03 the only potential features that are in the works are things that core does not want to support (https://github.com/ansible-community/antsibull-docs/pulls) 16:34:20 even this one? - https://github.com/ansible-community/antsibull-docs/pull/99 16:35:13 that's not really a feature, that's more a bugfix - but it's not really related to the docsite anyway (right now the sh restriction is enforced by the antsibull-core dependency) 16:35:21 ah ok thanks 16:35:29 ok next topic... 16:35:37 #topic opening up community docs build 16:35:59 Don Naro: you have updates/thoughts here? 16:36:32 hey yeah I can give an update. I've been poking away at this in the background and would like to get some thoughts from folks here. 16:39:02 #info as part of the initiative to open up the build for package docs I've looked at a number of options. one of the things that it's stuck on is the fact that you need a rather large host to handle the sphinx-build for the package docs. one of the options is doing a lift and shift of the content in docs/docsite from the ansible/ansible repository to another repo. 16:41:44 sorry, got disrupted by the family here 16:41:48 ok, back on track... 16:42:47 so TL;DR it looks like it might be possible to do one of two things. 1. leave a subset of the content in ansible/ansible and move the bulk of the docsite to a new repo. 2. do a complete move of the docsite to a new repo. 16:42:54 heh. it looked like you were typing the whole time 16:43:26 ha, well, I kinda was. just pausing to talk to wife and kids. 16:43:40 it's a bit of a hectic time in my day 16:44:16 oranod: how does this help with reducing the build size? 16:44:43 is content in ansible/ansible really the performace problem? Me thinks building the docs for all collections do hog the resources 16:44:44 might be worth summarizing why you think it's worth the forklifting of some/all docs out of the core repo so folks understand where this is coming from? 16:44:50 kristianheljas: yeah I had that impression as well... 16:45:31 it doesn't. the package docs build is what it is. we (well, someone else who is far better at these things than I) did a bunch of profiling and short of rewriting the RST parser there's not much we can actually do to get a performance gain 16:45:48 the job spends ages banging against compiled regex and stuff like that 16:46:27 i have heard that references are a huge strain 16:46:38 so the idea for the split here is that we could then separate CI for the package docs build and other doc operations like PR previews from the Ansible core CI 16:46:46 yes, like adding breadcrumbs increased build time and memory usage 16:47:06 with the split I think we could get an azp project with ephemeral instances on demand and avoid a lot of maintenance and security concerns 16:47:51 I don't want to make any promises and I don't have too much to show in how this would work yet but wanted to get the idea out and see what people in the community even think about it 16:48:12 I think the only way to speed up the build is to start building the docsite subtrees for every collection individually, and use some 'magic' to glue all of them together to one final docsite 16:48:25 +1 16:48:40 ah but I got the feeling there's more to this idea than just making things potentially faster? 16:48:52 the main problem with that is getting cross-collection references to work, and references from collections to the remainder of the docsite, and the other direction (remainder of the docsite to collection docsites) 16:49:13 yeah that's the main problem. building all those cross-refs 16:50:05 I have to leave, will read up the minutes later/tomorrow :) 16:50:09 the idea for the package docs build after the separation would be to basically fetch a specific ansible ref and build on top of that. so none of the dynamic generation would change 16:50:10 #unchair felixfontein 16:50:10 Current chairs: Don Naro briantist samccann tremble 16:50:30 bye felixfontein take care 16:50:31 felixfontein: have a nice evening! 16:50:33 thanks felixfontein ! 16:50:41 thanks everyone :) 16:51:43 WE have about 10 min left and so far this has covered the HOW we might do this.. Don Naro do you want to give any more detail on the WHY you are considering this? 16:52:54 as I mentioned it should give us the ability to get an Ansible community docs project that allows us to do on demand builds with ephemeral vms that don't punch a security hole in operations 16:53:26 I'm against the idea of self-hosted runners on public repos or putting secrets into ci workflows on repos that accept PRs 16:53:43 (dumping this update so it's in the minutes but we don't have to talk about it or address it now) 16:53:43 I have some interesting news that could affect the github-docs-build, specifically the publishing to GitHub Pages. GitHub has a beta option for pages where you can publish to it directly, without using the branch-based workflow, via a GitHub Actions Workflow (you can actually see that the branch-based workflow is using this stuff behind the scenes). 16:53:43 Interestingly, it works similarly to how our build/publish process already works, in that you have to upload an artifact, and then the publish action reads from the artifact: https://github.com/actions/deploy-pages 16:53:43 The cool thing about this is that GH has a separate permission set to publish to pages this way, so you don't need the workflow to have repo write access (which is one of the major concerns for RedHat-controlled repos and why some of them don't publish PR docs). 16:53:43 The major downside at the moment is that there's no way to publish a portion of the "site" this way, like we do now for PRs/branches/tags. But there's an alpha feature where they seem to specifically be working on an option to publish a "preview" site in PRs: https://github.com/actions/deploy-pages/blob/main/action.yml#L36 16:53:44 That would solve our PR issue, though we still might have some figuring out to do for multi-branch/tag. In any case, this is exciting news, and I'll keep on top of it. And we can start implementing some support for it without affecting our support for the current branch-based build, with a new set of shared workflows. 16:54:59 thanks briantist !! 16:55:15 oranod: for GHA, PRs that come from forks cannot access secrets in the repo, except with the `pull_request_target` trigger, in which the workflow doesn't run from the PR but from the target (it still requires careful consideration, and I can talk about that in detail since we use for the github-docs-build) 16:55:22 yes thanks a mill briantist 16:56:10 Don Naro: for the unwashed masses (namely me) - is this related to wanting to get rid of the internal jenkins jobs that run the docs builds today for publishing? 16:57:30 that's one side of it, yeah. I do think the primary driver is to make sure the package docs build is something that the community can take ownership of and directly work on. 16:58:07 the "separate the docsite" conversation has come up and I just want to really share that with the community and make sure to capture what folks are thinking about it. 16:58:26 if that very idea is appalling then let's abandon it 16:58:43 #info some of the drivers for this change include getting rid of the internal jenkins jobs the publish the docs... but primary driver is to make sure the package docs build is something the community can take ownership of and directly work on 16:58:43 so separating the docs would allow more experimentation around docs and make the folks see how it's get done? 16:59:46 I personally would be against removing core docs from the core repo. I feel docs should stay with the code. That said, some of the docs in ansible/ansible are not core-related but are more ansiblePackage related 17:00:11 kristianheljas: yes. we're driving to make sure community can do more of the operations development around docs and get the view into the build process. doing the docsite split might just be one way to achieve this. 17:00:29 personally I'm of the same mind as yourself samccann 17:00:34 idem 17:01:31 samccann has a good point, maybe we start using https://github.com/ansible/docsite instead? 17:02:02 ^ this is where i learned how to build the docs in the weekend 17:02:43 kristianheljas: nice. I noticed that but the convo happened late my time. did everything work out ok? 17:03:19 Yeah, buttersmooth - besides me starting frantically shopping for ram 🙂 17:04:22 sweet. yeah ram is kind of what we're up against here. it'd be sweet to sort of break the docs build up into separate actions but I don't think that's going to happen without a huge amount of work. 17:05:12 another option that is still possible is getting the budget for a GH enterprise runner that's a bit beefier than the default runners 17:06:10 I don't think it matters where it runs if logs are visible 17:06:23 there's also the potential to put things in read the docs, which I'm quite in favour of doing even though it might give less visibility with the logs 17:06:56 I like the idea of throwing $$/hardware at it actually... it seems like that would be sufficient for a very long time, our docsite will probably grow slower than the pace of hardware available at a certain price point, and it would save tons of effort 17:07:09 (says the guy who's not paying for it) :p 17:07:30 lol 17:09:15 I guess we're running a bit over time for the meeting but I'm happy to hang out and chat some more for sure 17:09:46 ok we can end the meeting if you think there's nothing more to log so to speak 17:09:57 or let it keep going a bit longer if the two of you want to chat more 17:09:58 So, the end. I agree with samccann that splitting up the docs content from ansible/ansible doesn't help us much. But maikng the build process public is a great initaitive to get things going, and i think it should happen in https://github.com/ansible/docsite 17:11:00 thanks kristianheljas it seems like the thinking is aligned there 17:12:16 samccann: I think we can call it. And you have time, i have a few questions about the boolean thing (it can be recorded as well if you wish) 17:12:27 #endmeeting