Package: rstdoc
Seebackground and documentation.Many companies useDOCXand thus produce an information barrier.
Working with text is more integrated in the (software) development process.
A final format can beDOCX, but, at least during development, text is better.Sphinxis an extension ofDocutilsused for many (software) projects,
but it does not support creation ofDOCXfiles, which certain companies demand.Pandocdoes supportDOCX, but does not support the Sphinx extensions,
hence:ref:and the like cannot be used.This python package supports working withRSTas documentation format without depending on Sphinx.link RST documents usingsubstitutions(generated in_links_xxx.r?st)create a.tagsfile to jump around in an editor that supportctagsRSThandling with python: reformat/createRSTtablespost-process Pandoc’s conversion fromDOCXtoRSTpre-process Pandoc’s conversion fromRSTtoDOCXSupport in building withWAF(orMakefile)expandSimpleTemplatetemplate files.stplgraphics files (.tikz,.svg,.dot,.uml,.epsor.stplthereof, and.pyg)
are converted to.pngand placed into./_imagesor<updir>/_images, if there, else into current directory.agenfile specifies howRSTshould be generated from source code files (seedcx.py)The conventions used are shownby the example produced viarstdcx--rest/--stpl/--over/--ipdtsmplfldrby the documentation sources that can be found athttps://github.com/rstdoc/rstdoc/tree/master/docpip install rstdocinstalls:ModuleCLI ScriptDescriptiondcxrstdcx, rstdoccreate.tags, labels and linksfromdocxrstfromdocxConvert DOCX to RST using PandoclisttablerstlisttableConvert RST grid tables to list-tablesuntablerstuntableConverts certain list-tables to paragraphsreflowrstreflowReflow paragraphs and tablesreimgrstreimgRename images referenced in the RST fileretablerstretableTransforms list tables to grid tablesrstdcxrestructuredText sources are split into two types of files:
main files considered by Sphinx, and included files.
Which of.restor.rstis main or included is determined
bysource_suffixin a<root>/conf.pyor opposite to the extension of the included_links_sphinx.r?stfile:if you have.. include:: /_links_sphinx.rest,
then the main file extension is.rstrstdoccreates documentation (PDF, HTML, DOCX)
from restructuredText (.rst,.rest) using eitherPandocSphinxDocutilsconfigurablerstdocandrstdcxcommand line tools calldcx.py.
whichcreates.tagsto jump around with the editorhandles.stplfilesprocessesgenfiles (see examples produced by –rest)creates links files (_links_docx.r?st,_links_sphinx.r?st, …)forwards known files to either Pandoc, Sphinx or DocutilsSee example at the end ofdcx.py.
It is supposed to be used with a build tool.makeandwafexamples are included.Initialize example tree (add--rstrestto make.rstmain and.restincluded files):$ ./dcx.py --rest repo #repo/doc/{sy,ra,sr,dd,tp}.rest files OR
$ ./dcx.py --stpl repo #repo/doc/{sy,ra,sr,dd,tp}.rest.stpl files
$ ./dcx.py --ipdt repo #repo/pdt/AAA/{i,p,d,t}.rest.stpl files
$ ./dcx.py --over repo #.rest all overOnly create .tags and_links_xxx.r?st:$ cd repo
$ rstdocCreate the docs (and .tags and_links_xxx.r?st) withmake:$ make html #OR
$ make epub #OR
$ make latex #OR
$ make docx #OR
$ make pdfThe latter two are done by Pandoc, the others by Sphinx.Create the docs (and .tags and_links_xxx.r?st) withwaf:Instead of usingmakeone can loaddcx.py(rstdoc.dcx) inwaf.wafalso considers all recursively included files,
such that a change in any of them results in a rebuild.
All files can have an additional.stplextension to useSimpleTemplate.$ waf configure #also copies the latest version of waf in here
$ waf –docs docx,sphinx_html,rst_odt
$ #or you provide –docs during configure to always compile the docsrst_xxx: viarst2xxx.pysphinx_xxx: viaSphinxandjustxxx: viaPandoc.The following image language files should be parallel to the.r?stfiles.
They are automatically converted to.pngand placed into./_imagesor<updir>/_imagesor else parallel to the file..tikzor.tikz.stpl.
This needs LaTex..svgor.svg.stpl.dotor.dot.stplThis needsgraphviz..umlor.uml.stplThis needsplantuml.
Provide eitherplantuml.batwith e.g.java-jar"%~dp0plantuml.jar"%*orplantumlsh script withjava-jar`dirname$BASH_SOURCE`/plantuml.jar"$@".epsor.eps.stplembedded postscript files.This needsinkscape..pygcontains python code that produces a graphic.
If the python code defines ato_svgor asave_to_pngfunction,
then that is used, to create a png.
Else the following is triedpyx.canvas.canvasfrom thepyxlibrary orcairocffi.Surfacefromcairocffimatplotlib.
Ifmatplotlib.pyplot.get_fignums()>1the figures result in<name><fignum>.pngThe same code or the file names can be used in a.r?st.stplfile
withpngembed()ordcx.svgembed()to embed in html output.{{!svgembed("egpyx.pyg",outinfo)}}
<%
ansvg=svgembed('''
from svgwrite import cm, mm, drawing
d=drawing.Drawing(viewBox=('0 0 300 300'))
d.add(d.circle(center=(2*cm, 2*cm), r='1cm', stroke='blue', stroke_width=9))
'''.splitlines(),outinfo)
%>
{{!ansvg}}ConventionsFilesmain files and included files:.rest,.rstor vice versa..txtare for literally included files (use :literal: option).templates separately rendered :*.rest.stpland*.rst.stpltemplate included:*.rst.tplTemplate lookup is done in.and..with respect to the current file.with%include('some.rst.tpl',param="test")with optional parameterswith%globals().update(include('utility.rst.tpl'))if it contains only definitionsLinks.. _`id`:arereST targets.
reST targets should not be template-generated.
The template files should have a higher or equal number of targets
than the generated file,
in order for tags to jump to the template original.
If one wants to generate reST targets,
then this should better happen in a previous step,
e.g. withgenfiles mentioned above.References use replacementsubstitutions:|id|.If you want an overview of the linking (traceability),
add.. include:: _traceability_file.rsttoindex.restor another.restparallel to it.
It is there in the example project, to include it in tests._traceability_file.{svg,png,rst}are all in the same directory.Link files are created in link roots, which are folders where the first main file
(.restor.rst) is encoutered during depth-first traversal.
Non-overlapping link root paths produce separately linked file sets... include::/_links_sphinx.r?st, with the one initial/instead of a relative or absolute path,
will automatically search upward for the_links_xxx.r?stfile
(_sphinxis replaced by what is needed by the wanted target when the docs are generated).Sphinxconf.pyis augmented by configuration for Pandoc and Docutils.
It should be where the input file is, or better at the project root
to be usable withwaf.See the example project created with--rest/stpl/ipdt/overand the sources of the documentation ofrstdoc.rstdcxCLIrstdcxis the same asrstdoc.Without parameters: creates|substitution|links and .tags ctags for reST targets.With two or three parameters: process file or dir to out file or dir
through Pandoc, Sphinx, Docutils (third parameter):html,docx,odt,pdf, … uses  Pandoc.rst_html,rst_odt,rst_pdf, …  usesrst2html, …sphinx_html,sphinx_pdf, …  uses Sphinx.
Sphinx provides a nice entry point via thesphinx bootstrap theme.4th parameter onward become python defines usable in.stplfiles.Pdf output needs latex. Else you can make odt or docx and usewin:swriter.exe--headless--convert-topdf Untitled1.odtlinux:lowriter--headless--convert-topdf Untitled1.odtInkscape (.eps, .svg), Dot (.dot), Planuml (.uml), latex (.tex,.tikz)
are converted to .png into./_imagesor<updir>/_imagesor ‘.’.
Any of the files can be a SimpleTemplate template (xxx.yyy.stpl).Configuration is inconf.pyor../conf.py.rstdoc--stpl|--rest|--ipdt|-overcreate sample project trees.--stplwith.rest.stpltemplate files,--restwith only a doc folder with.restfiles,--ipdtwith inform-plan-do-test enhancement cycles--overwith.restfiles all over the project tree including symbolic linksExamplesExample folders (see wscript and Makefile there):rstdoc --rest <folder> [--rstrest]
rstdoc --stpl <folder> [--rstrest]
rstdoc --ipdt <folder> [--rstrest]
rstdoc --over <folder> [--rstrest]Use--rstrestto produce.rstfor the main file,
as.restis not recognized by github/gitlab,
who also don’t support file inclusion,
so no need for two extension anyway.Examples usages with the files generated byrstdoc--stpltmp:cdtmp/docrstdcx#expand .stpl and produce .tag and _links_xxx files#expand stpl and append substitutions (for simple expansion use ``stpl <file> .``)rstdcxdd.rest.stpl-rest# expand to stdout, appending dd.html substitutions, to pipe to Pandocrstdcxdd.rest.stpl-html.# as beforerstdcxdd.rest.stpl-docx.# expand to stdout, appending dd.docx substitutions, to pipe to Pandocrstdcxdd.rest.stpl-newname.docx.# expand template, appending substitutions for target newname.docxrstdcxdd.rest.stpl-html# expand to stdout, already process through Pandoc to produce html on stdoutrstdcxdd.rest.stpl# as beforerstdcxsy.rest.stpl-rst_html# expand template, already process through Docutils to produce html on stdoutstplsy.rest.stpl|rstdcx--sy.html.# appending sy.html substitutions, e.g. to pipe to Pandocstpldd.rest.stpl|rstdcx--dd.html# appending tp.html substitutions and produce html on stdout via Pandocrstdcxdd.rest.stpldd.rest# expand into dd.rest, appending substitutions for target dd.htmlrstdcxdd.rest.stpldd.htmlhtml# expand template, process through Pandoc to produce dd.htmlrstdcxdd.rest.stpldd.html# as beforerstdcxdd.rest.stpldd.htmlrst_html# expand template, already process through Docutils to produce dd.htmlrstdcxdd.rest.stpldd.docx# expand template, process through Pandoc to produce dd.docxrstdcxdd.rest.stpldd.odtpandoc# expand template, process through Pandoc to produce dd.odtrstdcxdd.rest.stpldd.odt# as beforerstdcxdd.rest.stpldd.odtrst_odt# expand template, process through Docutils to produce dd.odtrstdcxdd.rest.stpldd.odtrst# as beforerstdcx.buildhtml# convert current dir to build output dir using pandocrstdcx.buildsphinx_html# ... using sphinx (if no index.rest, every file separately)#Sphinx is not file-oriented
#but with rstdcx you need to provide the files to give Sphinx ``master_doc`` (normally: index.rest)
#Directly from ``.stpl`` does not work with Sphinxrstdcxindex.rest../build/index.htmlsphinx_html# via Sphinx the output directory must be different#convert the graphics and place the into _images or <updir>/_images
#if no _images directory exists they will be placed into the same directoryrstdcxegcairo.pygrstdcxegdot.dot.stplrstdcxegeps.epsrstdcxegother.pygrstdcxegplt.pygrstdcxegpygal.pygrstdcxegpyx.pygrstdcxegsvg.svg.stplrstdcxegtikz.tikzrstdcxegtikz1.tikzrstdcxeguml.uml#Convert graphics to a png (even if _images directory exists):rstdcxeguml.umleguml.png#Files to other files:rstdocdd.rest.stpldd.restrstdocdd.rest.stpldd.htmlhtmlrstdocdd.rest.stpldd.htmlrstdocsr.rest.stplsr.htmlrst_htmlrstdocdd.rest.stpldd.docxrstdocdd.rest.stpldd.odtpandocrstdocdd.rest.stpldd.odtrstdocsr.rest.stplsr.odtrst_odtrstdocsr.rest.stplsr.odtrstrstdocindex.restbuild/index.htmlsphinx_html#Directories to other directories with out info:rstdoc.buildhtmlrstdoc.buildsphinx_htmlGrep with python re in .py, .rst, .rest, .stpl, .tpl:rstdoc --pygrep inlineGrep for keyword lines containing ‘png’:rstdoc --kw pngDefault keyword lines:.. {{{kw1,kw2
.. {kw1,kw2}
{{_ID3('kw1 kw2')}}
%__ID3('kw1 kw2')
:ID3: kw1 kw2rstfromdocxrstfromdocx: shell commandfromdocx: rstdoc moduleConvert DOCX to RST in a subfolder of current dir, named after the DOCX file.
It also createsconf.py,index.pyandMakefileand copiesdcx.pyinto the folder.Seerstdcxfor format conventions for the RST.There are options to post-process through:--listtable (--join can be provided)
--untable
--reflow (--sentence True,  --join 0)
--reimgrstfromdocx-lurgcombines 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.restfilerunrstfromdocx-lurgdoc1.docx; instead of -lurg use your own optionscheck the output in thedoc1subfolderrepeat the previous 2 steps with the next DOCX filescreate a new folder, e.g.docmerge all other folders into that new folderfromdocx.docx_rst_5creates 5 different rst files with different postprocessing.Seerstreflowfor an alternative proceeding.rstlisttablerstlisttable: shell commandlistable: rstdoc moduleConvert RST grid tables to list-tables.Convert grid tables in a file to list-tables. The result is output to stdout:$ listtable.py input.rstConvert several files:$ listtable.py input1.rst input2.rst
$ listtable.py *.rstUse pipe (butcatmight not keep the encoding):$ cat in.rst | listtable.py -  | untable.py - > out.rstOptions-j,--joine.g.002. Join method per column: 0=””.join; 1=” “.join; 2=”\n”.joinrstuntablerstuntable: shell commanduntable: rstdoc moduleConvert tables of following format to paragraphs with an ID.
The ‘-’ in ID is removed and the ID is made lower case.Boldis removed.ID-XY-00text goes hereID-XY-01text again goes hereIf 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 orfromdocx.pywill
need a pre-processing viarstlisttableto convert grid tables tolist-tabletables.
This is done in one step withrstfromdocx-ludoc.rst.rstreflowrstreflow: shell commandreflow: rstdoc moduleReflow 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.rstNoteDOCX to RST using Pandocrstfromdocx-lurgdoc.rstconverts a docx to RST and
does all the post-processing in one step.It is adviced, though, to compare the output with the original and do some manual
corrections here and there.rstreimgrstreimg: shell commandreimg: rstdoc moduleReimg 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,…).rstretablerstretable: shell commandretable: rstdoc moduleTransforms list tables to grid tables.This file also contains the code from
the Vim pluginvim-rst-tables-py3,
plus some little fixes.rstdocis used by the Vim pluginvim_py3_rst, which replacesvim-rst-tables-py3.