[Starlingx-discuss] [DOCS] API processing and conversion

[Waines, Greg]

Inlined comments below
Greg.

From: "Tullis, Michael L" <michael.l.tullis at intel.com>
Date: Friday, August 17, 2018 at 2:20 PM
To: "starlingx-discuss at lists.starlingx.io" <starlingx-discuss at lists.starlingx.io>
Cc: "Jones, Bruce E" <bruce.e.jones at intel.com>, "Khalil, Ghada" <Ghada.Khalil at windriver.com>, "Kinder, David B" <david.b.kinder at intel.com>, Greg Waines <Greg.Waines at windriver.com>, "Jolliffe, Ian" <Ian.Jolliffe at windriver.com>, "Arce Moreno, Abraham" <abraham.arce.moreno at intel.com>, "Rifenbark, ScottX" <scottx.rifenbark at intel.com>
Subject: [DOCS] API processing and conversion

All,

After a few more hours of technical investigation, sample builds, and script writing, Scott and I are convinced that the “new direction” outlined below is the way to go for StarlingX API content conversion into the new OpenStack tooling. For the October release, we are confident (and are now committing) that we can deliver clean reST source for the eight API manuals, building into HTML via Sphinx.
[Greg]

Will this include ?

·         Documentation of all StarlingX-specific REST APIs? ... i.e. formerly the sysinv REST APIs,

·         AND

·         Documentation of “INCREMENTAL” changes to OTHER OpenStack Services' (e.g. Nova, Neutron, Cinder, Glance, ...) REST APIs
for which StarlingX is still carrying NON-UPSTREAMED patches?

And what will the actual ‘deliverable’ be ?

·         .rst files ?

·         a tarball of PDFs and HTMLs generated from .rst files ?

·         external publishing of HTML pages generated from .rst files on a starlingx.io page ?

o    with option to download the PDF version
( hoping the later )

Greg.


We can provide more details in the upcoming docs meeting.

Thx.

-- Mike and Scott

From: Tullis, Michael L [mailto:michael.l.tullis at intel.com]
Sent: Wednesday, August 15, 2018 4:30 PM
To: Jones, Bruce E <bruce.e.jones at intel.com>; starlingx-discuss at lists.starlingx.io
Subject: Re: [Starlingx-discuss] Docs team meeting minutes 8/15

RE: regarding https://storyboard.openstack.org/#!/story/2002712 (converted APIs) for October.

I met with Scott today, and based on our early testing, we are feeling confident about our ability to deliver converted APIs. We decided on a new, more efficient methodology today (proposed in more detail below) and will be attempting our first conversion in the coming days.

RECENT FINDINGS


·         Converting from the raw XML looks problematic and may be unnecessary.

·         Pandoc can convert individual XML (including DocBook and WADL) files, but it cannot handle the variables, hierarchies and includes, which would case substantial sorting out and manual labor.

NEW DIRECTION


·         Start our conversion from the generated HTML. Ghada sent a sample the other day for one of the APIs (the large TGZ file), which we downloaded and inspected.

·         Based on our early findings, we believe the cleanest path is to start with this compiled HTML file, which sorts out all of the variables, hierarchy, and includes when it is compiled through the old build process.

·         Pandoc can convert HTML into reST. We do need to write a pre-processing script to handle some of the proprietary markup in the generated HTML. Scott and I are dedicating much of tomorrow to check into that and will circle back again on Friday.

·         This path is looking efficient and promising!

-- Mike and Scott

From: Jones, Bruce E [mailto:bruce.e.jones at intel.com]
Sent: Wednesday, August 15, 2018 2:42 PM
To: starlingx-discuss at lists.starlingx.io<mailto:starlingx-discuss at lists.starlingx.io>
Subject: [Starlingx-discuss] Docs team meeting minutes 8/15

We held our weekly Docs team call today.


Agenda & notes for the 8/15 team call:
    Please update your calendars to include a reminder for this meeting.
    Abraham volunteered to be the TL for this team

  *   Review storyboard open issues and prioritize.  Scope and size and decide which can be committed to the October release.
     *   We reviewed each story.   All stories and bugs for the release have been tagged stx.2018.10.
o    Developer Guide / API Documentation available as a source of information

  *   https://wiki.openstack.org/wiki/StarlingX/Developer_Guide/API_Documentation

  *   In particular, can we do https://storyboard.openstack.org/#!/story/2002712 for October?
o    Checking with our Tech Writing team

  *   What work items are missing from the current backlog?
o    Greg Waines has created a list of work items, initial stories created
§  https://wiki.openstack.org/wiki/StarlingX/Developer_Guide/API_Documentation#Work_Items

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.starlingx.io/pipermail/starlingx-discuss/attachments/20180820/5d1e4f96/attachment-0001.html>