Test and verify the contributed new asset documentation system

Task

Give the new documentation system a trial run to define any necessary steps before mainstreaming it for OpenCPI. This will lead to any other issues/tasks to actually perform the mainstreaming. This is based on MR !381 (merged), and will lead to that MR being reviewed and accepted.

The task that makes up the trial run is to convert existing OpenCPI core and platform asset data sheets to use the new documentation system. See below for details.

Location of documents

projects/core/components/backpressure.test/doc/backpressure.tex

projects/core/components/backpressure.test/doc/figures/

projects/core/components/file_read.test/doc/file_read.tex

projects/core/components/file_read.test/doc/snippets/messaging_snippet.tex

projects/core/components/file_read.test/doc/figures/

projects/core/components/file_write.test/doc/file_write.tex

projects/core/components/file_write.test/doc/snippets/messaging_snippet.tex

projects/core/components/file_write.test/doc/figures/

projects/core/components/metadata_stressor.test/doc/metadata_stressor.tex

projects/core/components/metadata_stressor.test/doc/figures/

projects/platform/hdl/devices/data_sink_qdac.test/doc/data_sink_qdac.tex

projects/platform/hdl/devices/data_sink.qdac.test/doc/figures/

projects/platform/hdl/devices/data_src_qadc.test/doc/data_src_qadc.tex

projects/platform/hdl/devices/data_src_qadc.test/doc/figures/

projects/platform/hdl/platforms/zed/doc/ZedBoard_Getting_Started_Guide.tex

projects/platform/hdl/platforms/zed/doc/figures/

projects/assets/hdl/devices/ad9361_config_proxy.test/doc/AD9361_Config_Proxy.tex

projects/assets/hdl/devices/ad9361_config.test/doc/AD9361_Config.tex

projects/assets/hdl/devices/ad9361_data_sub.test/doc/AD9361_Data_Sub.tex

projects/assets/hdl/devices/ad9361_spi.test/doc/AD9361_SPI.tex

doc/av/tex/snippets/Driver_Snippet.tex

Problem identified

OpenCPI is accepting the ML partner's "ocpidoc" tool, a document creation and generation tool based on Sphinx that takes asset sources documented in restructured text (RST) markup and generates HTML output using custom opencpi directives and an HTML theme provided by ReadTheDocs. The OpenCPI project plans to document its assets in RST format and use ocpidoc to generate them. In this phase of that project, OpenCPI assets in the core and platform projects with existing data sheets in LaTeX markup are to be converted to RST files and organized into the directory and file hierarchy expected by the "ocpidoc" tool so that it can generate per-project HTML "documents" for these assets. The configuration file for the HTML output supplied by the ML partners is also to be modified to follow OpenCPI documentation conventions.

Proposal or work around

  1. Set up asset directory and file hierarchy for each project following conventions for "ocpidoc" (see the ML partner SDR component library for an example) and using "ocpidoc" tool to generate templates.

  2. Convert the content of LaTeX-formatted data sheets for each project to RST markup, using the "ocpidoc" tool to create templates for the different asset types.

  3. Run the "ocpidoc" tool to create the new HTML asset document for the project and verify/fix problems.

  4. Modify the "ocpidoc" tool configuration file (conf.py) to accommodate OpenCPI documentation conventions and look and feel.

  5. For data sheet figures that have LibreOffice source (ODT), create Scalable Vector Graphics (*.svg) versions for use with the new doc tool format. Use the existing PNG and JPG files for figures that do not have source.

  6. Report problems and issues with the doc tools to the ML partner for resolution and/or consideration.

Edited by Lisa Zahn