PDF build for documentation

[cristianmihaipopa]

Using RTF2PDF, there is now the option for outputting the whole HDL documentation in PDF format. The following changes were made:

• new variable used to signal PDF output mode, called ADOC_MEDIA_PRINT (export ADOC_MEDIA_PRINT=value)
  • 1 for PDF output mode, which changes the HTML output a little bit (only visually, for example some things are not highlighted anymore); used this only when exporting to PDF
  • 0 default, no need to be set
• to build the PDF, use this command sphinx-build -b pdf . _build/pdfbuild in docs folder after setting the ADOC_MEDIA_PRINT variable; these libraries are needed to be installed
  • rst2pdf
  • matplotlib
  • svglib
• conf.py file from each repo needs to be changed to include rst2pdf.pdfbuilder extension
• the code that handles tables, collapsible etc. was changed so that the exported text is rendered correctly in PDF

There are a few more issues that need to be tackled, but these problems are more styling related:

• some pictures are not properly sized, meaning that in some cases they are too small or too big
• in some cases, code examples (blocks which contain highlighted code) exit the page, they are not wrapped to continue on the next line
• a few .svg diagrams are not properly rendered (missing port names or connections between blocks)

This is a prototype, a bit more styling is needed, but functionally, all the info that is contained in HDL documentation can be found in the new outputted PDF document (no missing tables, like in the case of collapsible content which contained other pieces of information).
The new PDF output method was tested on a select batch of pages from HDL (taken from docs/projects & docs/library) & on the whole HDL documentation.

[gastmaier]

Please add relevant docs for ADOC_MEDIA_PRINT on docs_guidelinesr.rst .
Can be after the Versioning section.

[gastmaier]

Is this necessary? I don't want to manually increment this every time.
I prefer injecting it in CI with the ADOC_DOC_VERSION environment variable based on the git release tag, that may or may not be a python version variable.
The option from ..adi_doctools/__init__ import __version__ as version is fine for python projects like this one and pyadi-iio, but not for others like scopy, iio-osc, etc.

[cristianmihaipopa]

This field is necessary as it specifies on the first page of the PDF the mentioned version of the document. If we don't want to specify the version, I will remove this field or will change it so that it automatically updates.