rstdoc - support documentation in restructedText (rst)
Project description
rstdoc
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.
This python packages supports working with RST as documentation format without depending on Sphinx:
link RST documents (_links_xxx.rst files)
create a .tags file to jump around in an editor that support ctags
Support in building with WAF or Makefile
expand SimpleTemplate template files .stpl
.tikz, .svg, .dot, .uml or .plt, or .stpl thereof, are converted to .png and placed into ./_images or ../_images
generated files from source code using a gen file
The conventions used are shown
by the example produced via rstdcx --init samplerstdoc
by the documentation sources that can be found at https://github.com/rpuntaie/rstdoc/tree/master/src/doc
pip install rstdoc installs:
Module |
Script |
Description |
---|---|---|
dcx |
rstdcx |
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 |
html, docx, pdf, … uses Pandoc.
sphinx_html, sphinx_pdf uses Sphinx. Sphinx provides a nice entry point via the sphinx bootstrap theme.
rstdcx
Support script to create documentation (PDF, HTML, DOCX) from restructuredText (RST).
For HTML Sphinx is used.
For PDF Pandoc is used (Sphinx would work, too).
For DOCX Pandoc is used, therefore no Sphinx extension.
rstdcx, or dcx.py
processes gen files (see examples produced by –init)
creates .tags _links_pdf.rst _links_docx.rst _links_sphinx.rst
See example at the end of dcx.py.
Usage
With rstdoc installed, ./dcx.py in the following examples can be replaced by rstdcx.
Initialize example tree:
$ ./dcx.py --init tmp
Only create .tags and _links_xxx.rst:
$ cd tmp/src/doc $ ./dcx.py
Create the docs (and .tags and _links_xxx.rst) with make:
$ make html $ make epub $ make latex $ make docx $ make pdf
The latter two are done by Pandoc, the others by Sphinx.
Create the docs (and .tags and _links_xxx.rst) with waf (preferred):
Instead of using make one can load dcx.py in waf. waf also considers all recursively included files, such that a change in any of them results in a rebuild of the documentation. All files can have an additional .stpl extension to use SimpleTemplate.
$ waf configure $ waf –docs docx,sphinx_html
Images are placed into ./_images or ../_images. The following image languages should be parallel to the .rest files and are automatically converted to .png and and placed into images.
.tikz or .tikz.stpl. This needs LaTex and sphinxcontrib-tikz and is rather slow.
.svg or .svg.stpl
.dot or .dot.stpl
.uml or .uml.stpl This needs a plantuml.bat with e.g. java -jar %~dp0plantuml.jar %* or plantuml sh script with java -jar `dirname $BASH_SOURCE`/plantuml.jar "$@".
.plt should contain python matplotlib code with one show() line
Conventions
Files
main docs end in .rest
.rst are included and ignored by Sphinx (see conf.py).
.txt are literally included (use :literal: option).
templates x.rest.stpl and y.rst.stpl are rendered separately before .. include: y.rst.
some.rst.tpl are template included Template lookup is done in in . and .. with respect to the current file.
with %include('some.rst.tpl',param="test") with optional parameters
with %globals().update(include('utility.rst.tpl')) if it contains only definitions
.. _`id`: are targets. RST targets must not be template-generated. The templates can have more targets than the generated file. If one wants to generate also rst targets, then this must happen in a previous step, e.g. with gen.
References use replacement substitutions: |id|.
See the example created with --init at the end of this file and the sources of the documentation of rstdoc.
rstfromdocx
rstfromdocx: shell command fromdocx: rstdoc module
Convert DOCX to RST in a subfolder of current dir, named after the DOCX file. It also creates conf.py, index.py and Makefile and copies dcx.py into the folder.
See rstdcx for format conventions for the RST.
There are options to post-process through:
--listtable (--join can be provided) --untable --reflow (--sentence True, --join 0) --reimg
rstfromdocx -lurg combines all of these.
To convert more DOCX documents into the same RST documentation folder, proceed like this:
rename/copy the original DOCX to the name you want for the .rest file
run rstfromdocx -lurg doc1.docx; instead of -lurg use your own options
check the output in the doc1 subfolder
repeat the previous 2 steps with the next DOCX files
create a new folder, e.g. doc
merge all other folders into that new folder
fromdocx.docx_rst_5 creates 5 different rst files with different postprocessing.
See rstreflow for an alternative proceeding.
rstlisttable
rstlisttable: shell command listable: rstdoc module
Convert RST grid tables to list-tables.
Usage
Convert grid tables in a file to list-tables. The result is output to stdout:
$ listtable.py input.rst
Convert several files:
$ listtable.py input1.rst input2.rst $ listtable.py *.rst
Use pipe (but cat might not keep the encoding):
$ cat in.rst | listtable.py - | untable.py - > out.rst
Options
- -j, --join
e.g.002. Join method per column: 0=””.join; 1=” “.join; 2=”\n”.join
rstuntable
rstuntable: shell command untable: rstdoc module
Convert tables of following format to paragraphs with an ID. The ‘-’ in ID is removed and the ID is made lower case. Bold is removed.
ID-XY-00 |
text goes here |
ID-XY-01 |
text again goes here |
If the first entry does contain no word chars or spaces between words, then the table stays. For a different behavior replace paragraph23.
A file produced from a docx using pandoc or fromdocx.py will need a pre-processing via rstlisttable to convert grid tables to list-table tables. This is done in one step with rstfromdocx -lu doc.rst.
rstreflow
rstreflow: shell command reflow: rstdoc module
Reflow tables and paragraphs in a rst document produced from a docx.
Post-process a docx in this order:
rstfromdocx doc.docx rstlisttable doc/doc.rst > doc/tmp.rst rstuntable doc/tmp.rst > doc/tmp1.rst rstreflow doc/tmp1.rst > doc/tmp2.rst rstreimg doc/tmp2.rst > doc/tmp3.rst rm doc/doc.rst mv doc/tmp3.rst doc/doc.rst rm doc/tmp*
Check the intermediate results.
Else one can also do inplace:
rstfromdocx doc.docx rstlisttable -i doc/doc.rst rstuntable -i doc/doc.rst rstreflow -i doc/doc.rst rstreimg -i doc/doc.rst
rstreimg
rstreimg: shell command reimg: rstdoc module
Reimg renames the images in the rst file and the files themselves. It uses part of the document name and a number as new names.
This is useful, if more RST documents converted from DOCX should be combined in one directory and the names of the images have no meaning (image13,…).
rstretable
rstretable: shell command retable: rstdoc module
Transforms list tables to grid tables.
This file also contains the code from the Vim plugin vim-rst-tables-py3, plus some little fixes. rstdoc is used by the Vim plugin vim_py3_rst, which replaces vim-rst-tables-py3.
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.