rstdoc - support documentation in restructedText (rst)


Keywords
Documentation
License
MIT
Install
pip install rstdoc==1.8.2

Documentation

rstdoc(1) Version 1.8.2 | rstdoc

See background and documentation.

Many companies use DOCX and thus produce an information barrier. Working with text is more integrated in the (software) development process. A final format can be DOCX, but, at least during development, text is better.

Sphinx is an extension of Docutils used for many (software) projects, but it does not support creation of DOCX files, which certain companies demand. Pandoc does support DOCX, but does not support the Sphinx extensions, hence :ref: and the like cannot be used.

This python package supports working with RST as documentation format without depending on Sphinx.

  • link RST documents using substitutions (generated in _links_xxx.r?st)
  • create a .tags file to jump around in an editor that support ctags
  • RST handling with python: reformat/create RST tables
  • post-process Pandoc's conversion from DOCX to RST
  • pre-process Pandoc's conversion from RST to DOCX
  • Support in building with WAF (or Makefile)
    • expand SimpleTemplate template files .stpl
    • graphics files (.tikz, .svg, .dot, .uml, .eps or .stpl thereof, and .pyg) are converted to .png and placed into ./_images or <updir>/_images, if there, else into current directory.
    • a gen file specifies how RST should be generated from source code files (see dcx.py)

The conventions used are shown

pip install rstdoc installs:

Module CLI Script Description
dcx `rstdcx`_, rstdoc create .tags, labels and links
fromdocx `rstfromdocx`_ Convert DOCX to RST using Pandoc
listtable `rstlisttable`_ Convert RST grid tables to list-tables
untable `rstuntable`_ Converts certain list-tables to paragraphs
reflow `rstreflow`_ Reflow paragraphs and tables
reimg `rstreimg`_ Rename images referenced in the RST file
retable `rstretable`_ Transforms list tables to grid tables