16:01:34 <samccann> #startmeeting Documentation Working Group aka DaWGs
16:01:34 <zodbot> Meeting started Tue Feb 21 16:01:34 2023 UTC.
16:01:34 <zodbot> This meeting is logged and archived in a public location.
16:01:34 <zodbot> The chair is samccann. Information about MeetBot at https://fedoraproject.org/wiki/Zodbot#Meeting_Functions.
16:01:34 <zodbot> Useful Commands: #action #agreed #halp #info #idea #link #topic.
16:01:34 <zodbot> The meeting name has been set to 'documentation_working_group_aka_dawgs'
16:01:59 <samccann> @room Meeting time! Who is here to talk the docs?
16:01:59 <tremble> o/
16:02:00 * kristianheljas is listening along, likely wont talk much, but would like to catch samccann later on
16:02:02 <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!
16:02:05 <samccann> #chair tremble
16:02:05 <zodbot> Current chairs: samccann tremble
16:02:08 <oranod> o/
16:02:25 <samccann> kristianheljas: cool thanks!
16:02:27 <samccann> #chair Don Naro
16:02:27 <zodbot> Current chairs: Don Naro samccann tremble
16:02:37 <samccann> 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 <samccann> 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 <samccann> felixfontein: briantist - around to talk docs today?
16:03:31 <felixfontein> o/
16:03:52 <samccann> #chair felixfontein
16:03:52 <zodbot> Current chairs: Don Naro felixfontein samccann tremble
16:03:58 <samccann> welcome welcome everyone!
16:04:27 <samccann> Agenda is https://github.com/ansible/community/issues/678#issuecomment-1430071104
16:04:38 <samccann> #topic Action Item updates
16:04:45 <samccann> #info open -Looking for  community maintainer(s) for the sphinx ansible theme
16:05:03 <briantist> o/
16:05:06 <samccann> I'm wondering if we should be requesting this in other channels? I think it was mentioned in the bullhorn once
16:05:11 <samccann> #chair briantist
16:05:11 <zodbot> Current chairs: Don Naro briantist felixfontein samccann tremble
16:05:14 <samccann> Welcome!
16:05:45 <oranod> welcome indeed
16:05:54 <felixfontein> are there any thoughts of replacing the theme completely? like getting rid of the current way the top bar is done?
16:06:13 <felixfontein> ('replacing' could be 'create a new major version which is very different from the old one')
16:06:23 <oranod> 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 <oranod> I think new major version would be great felixfontein and I'd be interested in contributing to it
16:07:07 <samccann> felixfontein: interestingly that top bar was 'inherited' by the Ansible.com stuff, but ...wow has that site changed!
16:07:18 <samccann> So my nickel is we an surely reconsider that part of it
16:07:53 <samccann> for those following along, we're talking about the black bar at docs.ansible.com.
16:07:55 <felixfontein> I'm happy to help if that ugly thing (from a technical POV) doesn't have to stay ;)
16:08:06 <samccann> AHAHAHA
16:08:07 <felixfontein> it's causing problems all over (see the recent bug)
16:08:27 <felixfontein> well, most of them are due the way it is implemented
16:09:01 <samccann> hmm I'm missing 'the recent bug'  do you have a link?
16:09:04 <samccann> I don't see new issues here -https://github.com/ansible-community/sphinx_ansible_theme/issues
16:10:00 <felixfontein> https://github.com/ansible-community/sphinx_ansible_theme/issues/84 this one
16:10:32 <samccann> ah ok
16:10:45 <felixfontein> it's caused by hacks to work around the issues introduced by the header bar :)
16:10:56 <samccann> So there's also a 'ng theme' issue there. So we're definitely willing to change
16:10:59 <felixfontein> (and the solution is to add another hack to that list of hacks...)
16:12:34 <samccann> 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 <samccann> As Don has pointed out, we are community docs and most of that bar is:
16:12:58 <samccann> a - product focused
16:13:04 <samccann> b- likely woefully outdated
16:13:34 <samccann> #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 <samccann> 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 <oranod> not at all
16:14:57 <samccann> ok so what's our next action to take on this? There's already an issue for 'ng theme'.
16:15:20 <samccann> https://github.com/ansible-community/sphinx_ansible_theme/issues/41
16:15:48 <oranod> maybe it would be nice to decide on what the community needs out of a new theme
16:16:31 <briantist> new theme will be entirely flash-based, yeah?
16:17:10 <oranod> 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 <felixfontein> it would definitely help (potential) maintainers to know what the actual requirements are
16:18:14 <samccann> ok so the question then in my mind -
16:18:30 <samccann> do we 'fix' what is currently there (even if it means removing the top header)
16:18:42 <samccann> or do we move on to some future wonderful live is grand theme?
16:19:08 <samccann> s/live/life/
16:19:27 <felixfontein> 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 <oranod> 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 <samccann> ok we can definitely followup with the person who created that issue
16:21:01 <oranod> I can take an action to discuss this with Sviat and get back to the DaWGs next week
16:21:36 <samccann> #action Don Naro to follow up with current maintainer of ansible-sphinx-theme on proposal to replace it with something else
16:21:57 <samccann> 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 <oranod> 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 <oranod> 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 <samccann> ok Don - can you open an issue on the community-team repo to 'evaluate creating a new theme for ansible docs'
16:27:13 <samccann> We can use that to track ideas, and if Sviat is interested in helping etc
16:27:42 <oranod> will do
16:27:55 <samccann> #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 <samccann> #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 <samccann> So that's the way we'll prototype a new docsite ^^
16:28:36 <samccann> #info closed samccann to update docs requirements versions before Feb 20
16:29:35 <samccann> 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 <felixfontein> 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 <felixfontein> (sorry got a bit side-tracked)
16:30:42 <samccann> 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 <samccann> so...we have a bit more time if antsibull-docs features are still in the works
16:31:19 <samccann> Thanks felixfontein  yeah would want to have a few people helping for sure
16:31:46 <kristianheljas> what is core branch pull?
16:32:08 <samccann> when the core team branches stable-2.15
16:32:18 <samccann> https://docs.ansible.com/ansible/devel/roadmap/ROADMAP_2_15.html#release-phase
16:32:21 <kristianheljas> Ah 🙂
16:32:24 <kristianheljas> Thanks!
16:33:01 <samccann> 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 <felixfontein> 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 <samccann> even this one? - https://github.com/ansible-community/antsibull-docs/pull/99
16:35:13 <felixfontein> 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 <samccann> ah ok thanks
16:35:29 <samccann> ok next topic...
16:35:37 <samccann> #topic opening up community docs build
16:35:59 <samccann> Don Naro: you have updates/thoughts here?
16:36:32 <oranod> 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 <oranod> #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 <oranod> sorry, got disrupted by the family here
16:41:48 <oranod> ok, back on track...
16:42:47 <oranod> 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 <samccann> heh. it looked like you were typing the whole time
16:43:26 <oranod> ha, well, I kinda was. just pausing to talk to wife and kids.
16:43:40 <oranod> it's a bit of a hectic time in my day
16:44:16 <felixfontein> oranod: how does this help with reducing the build size?
16:44:43 <kristianheljas> is content in ansible/ansible really the performace problem? Me thinks building the docs for all collections do hog the resources
16:44:44 <samccann> 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 <samccann> kristianheljas: yeah I had that impression as well...
16:45:31 <oranod> 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 <oranod> the job spends ages banging against compiled regex and stuff like that
16:46:27 <kristianheljas> i have heard that references are a huge strain
16:46:38 <oranod> 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 <felixfontein> yes, like adding breadcrumbs increased build time and memory usage
16:47:06 <oranod> 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 <oranod> 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 <felixfontein> 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 <kristianheljas> +1
16:48:40 <samccann> ah but I got the feeling there's more to this idea than just making things potentially faster?
16:48:52 <felixfontein> 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 <oranod> yeah that's the main problem. building all those cross-refs
16:50:05 <felixfontein> I have to leave, will read up the minutes later/tomorrow :)
16:50:09 <oranod> 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 <felixfontein> #unchair felixfontein
16:50:10 <zodbot> Current chairs: Don Naro briantist samccann tremble
16:50:30 <oranod> bye felixfontein take care
16:50:31 <kristianheljas> felixfontein: have a nice evening!
16:50:33 <samccann> thanks felixfontein !
16:50:41 <felixfontein> thanks everyone :)
16:51:43 <samccann> 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 <oranod> 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 <oranod> 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 <briantist> (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 <briantist> 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 <briantist> 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 <briantist> 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 <briantist> 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 <briantist> 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 <samccann> thanks briantist !!
16:55:15 <briantist> 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 <oranod> yes thanks a mill briantist
16:56:10 <samccann> 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 <oranod> 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 <oranod> 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 <oranod> if that very idea is appalling then let's abandon it
16:58:43 <samccann> #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 <kristianheljas> so separating the docs would allow more experimentation around docs and make the folks see how it's get done?
16:59:46 <samccann> 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 <oranod> 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 <oranod> personally I'm of the same mind as yourself samccann
17:00:34 <bcoca> idem
17:01:31 <kristianheljas> samccann has a good point, maybe we start using https://github.com/ansible/docsite instead?
17:02:02 <kristianheljas> ^ this is where i learned how to build the docs in the weekend
17:02:43 <oranod> kristianheljas: nice. I noticed that but the convo happened late my time. did everything work out ok?
17:03:19 <kristianheljas> Yeah, buttersmooth - besides me starting frantically shopping for ram 🙂
17:04:22 <oranod> 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 <oranod> 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 <kristianheljas> I don't think it matters where it runs if logs are visible
17:06:23 <oranod> 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 <briantist> 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 <briantist> (says the guy who's not paying for it) :p
17:07:30 <oranod> lol
17:09:15 <oranod> 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 <samccann> ok we can end the meeting if you think there's nothing more  to log so to speak
17:09:57 <samccann> or let it keep going a bit longer if the two of you want to chat more
17:09:58 <kristianheljas> 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 <oranod> thanks kristianheljas it seems like the thinking is aligned there
17:12:16 <kristianheljas> 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 <samccann> #endmeeting