Converting markdown files to reStructuredText
Converting markdown files to reStructuredText
- Pandoc is used for initial converting of Markdown files to rst. These pandoc converted rst files require some manual changes for it to render proper pdf. To convert the rst to pdf we are using rst2pdf tool.
All the changes are performed in experiment branch of cip documentation
- Please find the changes here : https://gitlab.com/cip-project/cip-documents/-/tree/experiment?ref_type=heads
For Ensuring PlantUML Diagrams rendering in PDFs . rst2pdf also has support for a number of features that require additional dependencies. Installation of all the required dependencies using pipx may be installed using:
-
pipx install rst2pdf[aafiguresupport,mathsupport,plantumlsupport,rawhtmlsupport,sphinx,svgsupport]
-
changes required in CI
apt update && DEBIAN_FRONTEND=noninteractive apt install python3-pip python3-venv
pip install rst2pdf
pipx install rst2pdf[plantumlsupport,sphinx,svgsupport]
Known issues and limitation
- Issue: Unable to add footer and page numbers to PDFs generated by gitlab CI
- Issue: Unable to scale CIP logo in the PDFs generated by gitlab CI.
- Limitation: Readthedocs is generating a single PDF file for all the .rst files (cip-documents).
- Limitation: Unavailability of proper editor to generate grid format tables for .rst documents. Currently this is being done by using markdown monster to generate grid format tables.