update core component RST docs to be "exemplars" for OpenCPI asset doc creation
Location of document
$OCPI_ROOT_DIR/projects/core/components/*/*-index.rst
$OCPI_ROOT_DIR/project/core/components/*.hdl/*-worker.rst
$OCPI_ROOT_DIR/project/core/components/*.rcc/*-worker.rst
$OCPI_ROOT_DIR/project/core/components/*.test/doc/figures/*.svg, *.odg, *.png
Problem identified
There is no "exemplar" OpenCPI asset documentation for readers of the OpenCPI Documentation Writer Guide to reference. The core components that had data sheets in LaTeX format have RST documents, but they were converted using the older "ocpidoc" structure and format. They need to be updated to use the latest ocpidev RST doc structure and conventions described in the OpenCPI Documentation Writer Guide.
Proposal or work around
The task list is:
-
Rename all *-index.rst files to *-comp.rst (component RST docs) -
Rename all *-worker.rst files to *-hdl.rst (HDL worker RST docs) or *-rcc.rst (RCC worker RST docs) -
Update all component and worker diagrams to use conventions illustrated in Writer Guide asset doc section (updated back pressure SVG file) -
Change all "Design" section headings to be "Function" in component RST docs -
Move all diagrams/figures to be located with their RST doc and out of *.test/doc. Delete the doc/ directory and .test directories for file_read and file_write. -
In file_read-index.rst, change the section heading "Operating mode" to "Operating Mode" (capitalize "Mode") -
In the metadata stressor HDL worker RST doc file, update the worker block diagram to show worker-specific properties, not just component properties
Acceptance criteria
-
The task list above has been completed. -
The updated docs build successfully with "ocpidev build --doc-only" -
The updated docs build successfully with the build-pages.py doc generator.
Edited by Lisa Zahn