[Starlingx-discuss] Docs team meeting minutes 8/15

[Rifenbark, ScottX]

Hi,

Initial pandoc conversion of a <apidoc>.html file to a <apidoc>.rst file seemed good.  Created an index.rst file to include the <apidoc>.rst file in the contents and then used "make" to make the HTML manual.  Bunch of warnings but it displays... only the tables are messed up.  They are not created with any column integrity.

Scott

From: Tullis, Michael L [mailto:michael.l.tullis at intel.com]
Sent: Wednesday, August 15, 2018 3: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/20180816/0cbc1539/attachment-0001.html>