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@intel.com]
Sent: Wednesday, August 15, 2018 3:30 PM
To: Jones, Bruce E <bruce.e.jones@intel.com>; starlingx-discuss@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@intel.com]
Sent: Wednesday, August 15, 2018 2:42 PM
To: starlingx-discuss@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

o   Developer Guide / API Documentation available as a source of information

o   Checking with our Tech Writing team

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