[Starlingx-discuss] [docs] [meeting] Docs team notes 2020-10-28

[Camp, MaryX]

Hello all,
Here are this week's docs team meeting minutes (short form). Details in [2].
Join us if you have interest in StarlingX docs! We meet on Wednesdays 12:30 PST.

  [1]   Call logistics: https://wiki.openstack.org/wiki/Starlingx/Meetings 
  [2]   Tracking Etherpad: https://etherpad.openstack.org/p/stx-documentation 

thanks,
Mary Camp
==========
2020-10-28
Note that the regular Docs meeting was cancelled. Upstreaming was the only topic for this meeting.

Status:  
   Node Management and System Configuration reviews resubmitted by Drake, this includes the first round of updates. Please take a look. Drake is having some PC issues with certificates. 
   Keane is working away, no specific update from him.
   Planning doc has someone assigned to it now.  
   Ron submitted the Data Networks guide last week. He has the Fault Management guide about ready to submit, probably by end of week. 

Juanita has reviewed the Node Management guide, she's been reviewing the TOC and marking it up. 
A few topics should be removed and a few new ones need to be added. She will follow up with Greg.

Email about handling code snippets - no easy answers here. Need to talk to Greg about the impact and possible solutions.

Some WindRiver codeblocks that differ from the StarlingX versions. For example, WindRiver uses wr-openstack as an app name in commands where StarlingX uses stx-openstack. 
We can't use substitutions to handle this because they are not interpreted in codeblocks. 
 
Possible alternatives to code blocks for this scenario:
There is a directive called parsed-literal; like a codeblock but substitutions are parsed:
 
.. parsed-literal::
    $ echo "Hello |prod|"
 
The drawback is that it lacks other functionality: no line numbering, syntax highlighting, line emphasis etc.
 
The other alternative I've found is the literalinclude - like a codeblock, but the content is pulled from a source file that could vary between repos. 
It seems to support many/all features of code-blocks.
 
.. literalinclude:: example.rb
   :language: ruby
   :emphasize-lines: 12,15-18
   :linenos:
 
Why this matters:   CAT << EOF > filename xxxxx lines of code    
WindRiver uses this scenario a lot for users to copy/paste many lines of code when they need to create a file (for example, a configuration file). 

Using only and include directives to differentiate "partner" content from main STX content
   The include situation -- will it be transparent for all partners? Yes. If cloned from STX repostory, all the .include files on the STX side will be empty. 
   No proprietary info there. Everyone sees each other's empty files, no content.
   Ron has seen some instances where repeated content at the top of files (ie alarms and events).
   Instead of making 10 different files, Ron abstracted that out to the includes directory.

Rubric
   Ron was able to test locally and it worked as expected. 
   Next step he will submit a review to the openstackdocstheme repo because we won't know if it ireally works untill the change is merged.