tldr; We can now use markdown table syntax in RST file. Command for building docs is same as before (i.e. cmake -G \"Ninja Multi-Config\" -B build -DDOCS:STRING=YES && ninja -C build -f build-Release.ninja). This was achieved by modifying cmake docs command from ${SPHINX_EXECUTABLE} -b html to ${PYTHON_EXECUTABLE} ${CMAKE_CURRENT_SOURCE_DIR}/scripts/preprocessor.py --input ${SPHINX_SOURCE} --output ${SPHINX_SOURCE}/__output__ && ${SPHINX_EXECUTABLE} -b html. Preprocessor may be useful for other custom RST syntax in future. Additional RST parsing can be added to docs/scripts/preprocessor.py in future.
Now, we can write tables in RST file using markdown syntax. This is pretty much as simple as it can get re. writing the tables. Supporting this requires additional step before the docs build, because markdown syntax isn't allowed in final RST file.
Verbs
=====
.. toctree::
.. contents::
*******
Monadic
*******
Tally
#####
.. doxygenfunction:: tally
******
Dyadic
******
******
Tables
******
Write markdown table in RST file.
| fruit | color | startswith |
| ----- | ----- | ---------- |
| apples | red | a |
| oranges | orange | o |
So, when building the docs, I added a preprocessor step (to existing CMAKE build docs command). The preprocessor scans all the RST files and creates parsed copy of each RST file in docs/source__out__. I have added that folder to .gitignore.
For above example, the parsed RST would be:
Verbs
=====
.. toctree::
.. contents::
*******
Monadic
*******
Tally
#####
.. doxygenfunction:: tally
******
Dyadic
******
******
Tables
******
Write markdown table in RST file.
======= ====== ==========
fruit color startswith
======= ====== ==========
apples red a
oranges orange o
======= ====== ==========
Notice that markdown table has been replaced with valid RST (type 2) table.
tldr; We can now use markdown table syntax in RST file. Command for building docs is same as before (i.e.
cmake -G \"Ninja Multi-Config\" -B build -DDOCS:STRING=YES && ninja -C build -f build-Release.ninja). This was achieved by modifying cmake docs command from${SPHINX_EXECUTABLE} -b htmlto${PYTHON_EXECUTABLE} ${CMAKE_CURRENT_SOURCE_DIR}/scripts/preprocessor.py --input ${SPHINX_SOURCE} --output ${SPHINX_SOURCE}/__output__ && ${SPHINX_EXECUTABLE} -b html. Preprocessor may be useful for other custom RST syntax in future. Additional RST parsing can be added todocs/scripts/preprocessor.pyin future.Resolves https://github.com/codereport/jsource/issues/120.
Now, we can write tables in RST file using markdown syntax. This is pretty much as simple as it can get re. writing the tables. Supporting this requires additional step before the docs build, because markdown syntax isn't allowed in final RST file.
So, when building the docs, I added a preprocessor step (to existing CMAKE build docs command). The preprocessor scans all the RST files and creates parsed copy of each RST file in
docs/source__out__. I have added that folder to.gitignore.For above example, the parsed RST would be:
Notice that markdown table has been replaced with valid RST (type 2) table.
Then after building you will get a nice table.