geosolutions-it
Export of MS online doc to PDF
Description
Investigate if it is possible to configure Read the docs to export the MS online documentation (eg. in PDF format).
Documentation section involved
- [X] User Guide
- [X] Developer Guide
Other useful information
Ref https://github.com/geosolutions-it/MapStore2-C040/issues/614
@tdipisa @MV88
Outcome
ReadTheDocs doesn't have support for conversion of the documentation to PDF formats for Mkdocs based project but only Sphinx based projects. Due to this we cannot make the documentation downloadable as PDF from the download section.
So the alternatives is use of Mkdocs supported plugins that help pdf conversion.
Two possibilities
- With the use of the plugin
mkdocs-pdf-export-plugin, a PDF export button is made available in every page of the documentation allowing users to download every page invidually or download all the pages at once Sample of the online Mapstore documentation with PDF support can be seen here - With the use of the plugin
print-site, it adds an additional page that combines all pages, allowing easy exports to PDF using browser's inbuilt print functionality to the print the same.
Kindly let me know your thoughts on which approach to proceed with. Thanks!
@dsuren1 thank you. I will check your feedback and I will get back to you asap.
@tdipisa
mkdocs-pdf-export-plugin provides us with a usuable feature like download all pages at once with syles and assets retained with a dedicated export button out of the box. So we intend to move ahead with this plugin.
However there are few limitations,
- TOC in Mkdocs are not exported to the PDF. i.e Only md files are combined and exported at the moment
- Relative links in the downloaded pdf is malformed. A fix is suggested in the plugin but unfortunately it's not merged. So we might to fork and test the fix. If this fix works the same will be implemented as part of the issue else the internal doc navigation within pdf will not be possible
- The pdf file name is not dynamically configurable. Hence the downloaded pdf file will use the name
mapstore_documentation.pdf
Sample documentation is hosted here