15:32:15 <samccann> #startmeeting DaWGs aka Documentation Working Group Supplemental meeting
15:32:15 <zodbot> Meeting started Thu Jan 14 15:32:15 2021 UTC.
15:32:15 <zodbot> This meeting is logged and archived in a public location.
15:32:15 <zodbot> The chair is samccann. Information about MeetBot at http://wiki.debian.org/MeetBot.
15:32:15 <zodbot> Useful Commands: #action #agreed #halp #info #idea #link #topic.
15:32:15 <zodbot> The meeting name has been set to 'dawgs_aka_documentation_working_group_supplemental_meeting'
15:32:23 <samccann> #topic opening chatter
15:32:39 <samccann> oookay... anyone around to talk about the docsite split etc?
15:34:12 <dericcrago> I'm around
15:34:16 <lmodemal> \o/
15:34:24 <samccann> phew!  thought I'd be talking to the wind here!
15:34:37 <samccann> #chair lmodemal dericcrago
15:34:37 <zodbot> Current chairs: dericcrago lmodemal samccann
15:34:48 <lmodemal> haha!
15:35:11 <samccann> anyone else around? gundalow abadger1999 anderssson007_ ?
15:35:59 <acozine> o/
15:36:12 <samccann> #chair acozine
15:36:12 <zodbot> Current chairs: acozine dericcrago lmodemal samccann
15:36:29 <samccann> ok let's get started
15:36:39 <samccann> #topic Status of the docsite split proposal
15:37:04 <samccann> #info the proposal is at https://hackmd.io/TQmzyhCUSSKa22iFR_079A?both
15:37:16 <samccann> #info we have internal buyin to make this happen!
15:37:48 <samccann> So the strong feedback we got was to not unversion the developer guide at this point. So that will stay versioned
15:38:33 <samccann> #info we have a plan for how to achieve this - https://hackmd.io/x0VwaKSYQCaHGJR4LelSEw?view
15:39:13 <samccann> #info TL;DR; - two sites with nearly identical documentation for now since we are short on time. They will have separate urls and versions.
15:40:06 <samccann> #info tracking issue for all we have to accomplish this month - https://github.com/ansible/ansible/issues/72032
15:40:28 <samccann> ok that's a lot of infos.
15:40:43 <acozine> heh
15:41:55 <samccann> So basically, we have some jenkins builds to create (the internal magic that gets the rst to html to the docsites)
15:42:31 <samccann> And we have some makefile magic to create for something like `make core-docs` vs `make webdocs` etc
15:43:16 <samccann> and prove the pipeline still works when we've done all that (to pull in collection docs to the Ansible build )
15:44:38 <acozine> as we discussed on Tuesday, we're also looking at moving some docs out of ansible/ansible and into collections
15:44:55 <samccann> post feb though right?
15:45:01 <acozine> oh, yes
15:45:14 <acozine> we have enough on our plates right now
15:45:27 <samccann> should we switch the topic to 'problems to solve' or something?
15:45:49 <acozine> samccann: that sounds good
15:46:03 <acozine> I think we may be able to close this weekly meeting this week
15:46:30 <acozine> though we may want to start it up again after the first round of work is done and 3.0 is released
15:46:33 <samccann> #topic problems to solve
15:46:47 <samccann> yeah agreed, this may be the last one we need but we can discuss at the end
15:47:09 <samccann> one of the problems I thought about this am - how can we make the title of 'ansible-core' docs say Ansible Core?
15:47:41 <samccann> it's the same index.rst file.  So was wondering if sphinx has variable support like that. where we could set something in the conf.py/makefile to change  that title at least
15:48:16 <acozine> You mean the title above the left-hand nav?
15:48:43 <samccann> http://docs.testing.ansible.com/ansible-core/2.11/
15:48:59 <samccann> it says 'Ansible Documentation'.  I'd rather it said 'Ansible Core Documentation'
15:49:16 <acozine> yeah
15:49:45 <samccann> but that's in the index.rst file top heading.  I know rst allows variables, but you set them in the same file so that won't work. We need something we can set 'somewhere else' that the makefile can pick up and use. I'm hoping it's doable
15:50:06 <acozine> looks like they're called `substitutions` in sphinx
15:50:50 <samccann> got a pointer?
15:51:01 <acozine> https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#substitution-definitions
15:51:50 <acozine> The section on "replacement text" is the most useful to us
15:52:13 <samccann> yeah that's rst not sphinx. The examples I saw defined the substitution later in that same file. Maybe it works some other way as well?
15:52:26 <acozine> https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#substitution-references
15:53:40 <samccann> ok so maybe we can define the substitutions in separate files and include those files only in their  respective builds.
15:54:06 <acozine> https://sublime-and-sphinx-guide.readthedocs.io/en/latest/reuse.html
15:54:09 <samccann> #info rst substitutions might work - https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#substitution-definitions  and https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#substitution-references
15:54:38 <acozine> ahhh, here we go: https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#substitutions
15:55:11 <acozine> we should be able to do logic that says "if x use x_sub, if y use y_sub"
15:55:15 <samccann> #info see https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#substitutions for how to do  this w separate files
15:55:22 * acozine realizes she just signed herself up to do that owrk
15:55:26 <samccann> AAHAHAHA
15:55:42 <samccann> well it's up to you, but it's definitely an action item from this meeting ;-)
15:55:46 <samccann> for one of us to try
15:56:04 <lmodemal> I don't mind trying it out...get some practice in
15:56:13 <acozine> AFK 5 for household issue
15:56:13 <samccann> cool.. a volunteer!
15:56:25 <lmodemal> LOL
15:56:36 <samccann> #action lmodemal - attempt sphinx/rst variable substitution for the title
15:56:43 <lmodemal> Cool
15:57:22 <samccann> ok any other problems we know about that we want to spend some quality time brainstorming about here?
15:58:40 <samccann> #topic list of problems to solve
15:58:57 <samccann> #info this is an older list of problems abadger1999 created a few weeks ago - https://hackmd.io/iDEyihLqRtWnjtOUd3pNYQ
15:59:24 <samccann> Some of that has been punted to post feb (the collection /docs directory and moving scenario guides out of ansible/ansible)
16:00:13 <samccann> #info this problem still exists - https://hackmd.io/iDEyihLqRtWnjtOUd3pNYQ#Pipeline-uses-Ansible-version-to-set-the-version-in-the-URL-for-docs
16:00:37 <samccann> aka how to get the docs pipeline to recognize different versions since it currently I think uses `ansible --version` and that will stay tied to core
16:02:12 <acozine> our hacky override in the Jenkins job does work now
16:02:13 <samccann> for seo/ranking  - we will have canonical url on Ansible docs for /latest/ as the canonical url.  But for ansible-core, we will not use /latest/ at all and not have a canonical url to start
16:02:34 <samccann> sorry acozine - docs pipeline above meant antsibull
16:02:47 <acozine> yeah, and that's the right way to solve the problem
16:02:48 <samccann> that;s how I interpret that note in the problems doc anyway
16:03:11 <acozine> but we have less time pressure to solve it now
16:03:28 <acozine> since we have a workaround
16:03:38 <samccann> sorry i'm confused
16:04:10 <samccann> the anstibull script uses `ansible --version` for the url, and that only reflects ansible-core. So there's still a problem there for Ansible 3 isn't there?
16:04:29 <acozine> yes, but we can override it on publication in the Jenkins job
16:04:57 <samccann> ok we are talking apples and pineapples here
16:05:00 <acozine> heh
16:05:03 <samccann> yes, you fixed the jenkins stuff
16:05:15 <bcoca> apples and dairy cream
16:05:19 <samccann> and that may be what toshio's note referred to when he says 'pipeline'
16:05:35 <samccann> for me... pipeline has meant antsibull pulling in the collections index
16:06:06 <samccann> but maybe antsibull doesn't set a url at all... so maybe it's apples and dairy cream just in my head
16:06:06 <acozine> gotcha
16:06:35 <samccann> I can ping him later to be sure. I just read that doc again this am and  that popped out at me as potentially something we haven't solved for yet
16:07:15 <samccann> #action  samccann to clarify what  this problem really means - https://hackmd.io/iDEyihLqRtWnjtOUd3pNYQ#Pipeline-uses-Ansible-version-to-set-the-version-in-the-URL-for-docs
16:07:18 <acozine> yes, and that's the right solution, and we have more than 2 weeks available to solve it
16:07:36 <samccann> ok so time for...
16:07:42 <samccann> #topic Next Steps
16:08:03 <samccann> given we are into the implementation phase now, do we drop this extra meeting and fold updates etc into the regular docs meeting?
16:08:26 <lmodemal> I think that's a good idea.
16:08:49 <acozine> +1
16:09:01 <samccann> ok sounds like a plan
16:09:22 <samccann> #agreed we will stop having this extra meeting and fold updates/issues into the regular tuesday DaWGs meetings
16:10:16 <samccann> #info acozine working on jenkins build  samccann working on makefile  lmodemal working on variable subsitution
16:10:47 <samccann> #info abadger1999 investigating the antsibull side of this to see if it  'all works' or needs some changes
16:10:56 <acozine> #info more information also available on the project board at https://github.com/ansible/ansible/projects/27
16:10:59 <samccann> That's probably the next steps that  will take us to next Tuesday's meeting
16:11:17 <samccann> And for good measure...
16:11:22 <samccann> #topic Open Floor
16:11:49 <samccann> anyone have anything to bring up in regards to this docsite split that we haven't discussed here? This is your time to shine!
16:13:56 <samccann> okay!
16:14:09 <acozine> thanks samccann for running this and so many other meetings!
16:14:11 <samccann> well thanks everyone for coming and helping with this effort in an extra meeting these past few weeks!
16:14:24 <samccann> We'll see y'all on the regular Tuesday meeting!
16:14:28 <samccann> #endmeeting