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 (seedcx.py
)
- expand
SimpleTemplate
template files
The conventions used are shown
- by the example produced via
rstdcx --rest smplfldr
orrstdcx --stpl smplfldr
- by the documentation sources that can be found at https://github.com/rpuntaie/rstdoc/tree/master/doc
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 |