[Starlingx-discuss] [docs][meeting] Docs site theme (was: Docs team notes 2020-08-19)

[Jeremy Stanley]

On 2020-09-03 17:14:33 +0000 (+0000), Camp, MaryX wrote:
[...]
> In the STX docs meeting yesterday, we discussed your suggestion
> about forking the theme into the STX docs repo. The team agrees
> that this is the right time to implement it. Your guidance/help
> with this process is really appreciated.
[...]

My pleasure. Probably the place to start is copying the files from
the openstackdocstheme subdirectory of the
openstack/openstackdocstheme repository into the appropriate
locations for the doc/source tree of the starlingx/docs repository.
The up side to this move is that it will be tested completely with
draft renderings we can check over before it's ever approved and
deployed. I'll abandon https://review.opendev.org/749369 but we'll
want to make sure to incorporate a similar change into the new
extension script in starlingx/docs.

> We want to publish from a branch (not tags) and use the branch
> naming convention. "R4.01" was a typo in my original email.
> Corrected text:  Our planned URL structures are:
> https://docs.starlingx.io/R4.0 (current release) and
> https://docs.starlingx.io/latest for the master branch.

Great, thanks confirming! That will make all this a lot simpler than
trying to derive version numbers from something other than the
branch name.

> Please let me know about next steps and recommended actions.

I outlined the general idea above, but the specifics will probably
take as much effort to write up as it would to just push an initial
attempt myself. I can have something up for review in the next day
or so with copies of the files in the places I expect they should
go, but I'm also no expert when it comes to Sphinx so am just as
happy for someone else to give it a shot instead, if there are any
volunteers for that (in which case I'll gladly help review and debug
the result).

> As an aside, since you mentioned these threads will live on in the
> ML archives forever, I'm wondering what the etiquette is for
> modifying the message subject line to be more relevant/useful?
> Maybe adding a descriptor to the end of the subject, like [theme]?

The conventional way, which I've done just now in this reply, is to
replace the subject but follow it with all or some of the old
subject in parentheses with a preceding "was:" to indicate this is a
subthread of the original discussion topic. The OpenStack community
documents this in their wiki article on Mailing List Etiquette,
though it's really just a long-standing entrenched tradition on most
of the technical mailing lists to which I've ever subscribed:

https://wiki.openstack.org/wiki/MailingListEtiquette#Changing_Subject

-- 
Jeremy Stanley
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 963 bytes
Desc: not available
URL: <http://lists.starlingx.io/pipermail/starlingx-discuss/attachments/20200903/b1ca1113/attachment.sig>