Affected Documentation Section
reference
Suggested Change
The product RNC file is stored under src/docbuild/config/xml/data/product-config-schema.rnc. This RNC file with all elements, attributes, and their purposes need to be documented.
In the ideal case, we document a thorough description of the purpose, the datatypes, and examples of elements and attributes.
Additional Context
Unfortunately, there is no direct way to do it. Some ideas to investigate further:
- Convert RNC -> RNG -> RST.
The first step can be done with the trang tool. The second step needs probably a more elaborate XSLT stylesheet to convert itto the RST format.
- Convert RNC -> RNG -> JSON
Once we have a JSON schema, we could use a Sphinx extension like lnoor/sphinx-jsonschema to document it with the .. jsonschema:: directive.
Whatever approach we choose, implementation wise we need to think about the following points:
- Which tools do we need to convert our RNC to RST? That's about dependencies and workflows.
- What steps do we have to execute to get our final RST file? That's about what do we add into the
Makefile.
Whenever something is changed in the product RNC file, a build with make docs triggers also a rebuild of the RST file.
I guess, it's okay to add the final RST file into the Git repo. This avoids errors when the doc is getting built. It's similar to the AutoAPI approach.
Related
See also #171
Affected Documentation Section
reference
Suggested Change
The product RNC file is stored under
src/docbuild/config/xml/data/product-config-schema.rnc. This RNC file with all elements, attributes, and their purposes need to be documented.In the ideal case, we document a thorough description of the purpose, the datatypes, and examples of elements and attributes.
Additional Context
Unfortunately, there is no direct way to do it. Some ideas to investigate further:
The first step can be done with the
trangtool. The second step needs probably a more elaborate XSLT stylesheet to convert itto the RST format.Once we have a JSON schema, we could use a Sphinx extension like lnoor/sphinx-jsonschema to document it with the
.. jsonschema::directive.Whatever approach we choose, implementation wise we need to think about the following points:
Makefile.Whenever something is changed in the product RNC file, a build with
make docstriggers also a rebuild of the RST file.I guess, it's okay to add the final RST file into the Git repo. This avoids errors when the doc is getting built. It's similar to the AutoAPI approach.
Related
See also #171