Re-enable PDF generation

[offtherailz]

Description

Because of changes reported in #9369 , we needed to temorary disable PDF generation. With #9373 we have a version of the PDF that works (videos are not included).

Anyway:

• the lib is quite old and not maintained
• it takes 500seconds to build
• Some issues (blank page at the beginning to solve) as well as update to latest mkdocs material

We have an alternative using with-pdf lib:

• 90s to build
• Table of contents
• Better layout
• Possibility of several customizations

It's configuration have to be added in mkdocs.yml file, with the following output.

plugins:
  - search
  - with-pdf:
      #author: WHO
      copyright: GeoSolutionsGroup
      #
      #cover: false
      #back_cover: true
      cover_title: MapStore Documentation
      cover_subtitle: User Guide and Developer Guide
      #custom_template_path: TEMPLATES PATH
      #
      #toc_title: TOC TITLE TEXT
      #heading_shift: false
      toc_level: 3
      #ordered_chapter_level: 2
      #excludes_children:
      #    - 'release-notes/:upgrading'
      #    - 'release-notes/:changelog'
      #
      exclude_pages:
      #    - 'user-guide/'
      #    - 'appendix/contribute/'
      #convert_iframe:
      #    - src: IFRAME SRC
      #      img: POSTER IMAGE URL
      #      text: ALTERNATE TEXT
      #    - src: ...
      #two_columns_level: 3
      #
      # render_js: true
      #headless_chrome_path: headless-chromium
      #
      output_path: pdf/mapstore_documentation.pdf
      enabled_if_env: ENABLE_PDF_EXPORT
      #
      #debug_html: true
      show_anchors: true
      #verbose: true

We have to evaluate

• if using this new lib or the old lib fixing the issues (evaluating quality of pdf and work to do)
• adding the proper link
• re-enable the PDF generation in readthedocs.io. (project settings, setting ENABLE_PDF_EXPORT=1, now is set to 0 due to the bad quality of the PDF generated)

[mahmoudadel54]

@offtherailz @tdipisa
Hey
I have implemented the use of with-pdf plugin initially with generating PDF and the layout seems good.
You can try it with this link:
https://mapstoreforkwithpdfplugin.readthedocs.io/en/issue_9383/
and downloading the pdf is here:

My notes:

• for the download links it can be added in the nav section like above, it can be added as a link in the Markdown files
• Videos are not visible in the pdf, is it normal behavior ?
• There is no blank pages like the previous plugin 'mkdocs-pdf-export-plugin'
• the build time with pdf generation is around 170 seconds which is better than the previous one 'mkdocs-pdf-export-plugin':
  ** with-pdf plugin build time with ENABLE_PDF_EXPORT=1
  

** mkdocs-pdf-export-plugin plugin build time with ENABLE_PDF_EXPORT=1

[tdipisa]

Dear @mahmoudadel54 Thank you so much for this. This seems really good. Some feedback below. @offtherailz will follow as soon as possible.

What is this? I think it should be fixed.

for the download links it can be added in the nav section like above, it can be added as a link in the Markdown files

I would like to:

• have it more visible than the one available at your link.
• Is it possible to have it in all pages?
• I would also like to have it with a clickable PDF icon
• Can we have the MS logo also in the first page just above the Title?

Videos are not visible in the pdf, is it normal behavior ?

Yes, also in the previous version was like that. Anyway, let me know if we can do something to improve for this and if you need time for this let me also know how much.

[mahmoudadel54]

Hi @tdipisa
I have implemented:

• Showing the download link of PDF at the navbar taps like:
  

• Putting author title "GeoSolutionsGroup" instead of none

• Adding MS logo for the cover page in PDF
  

You can check this link: https://mapstoreforkwithpdfplugin.readthedocs.io/en/issue_9383/

[tdipisa]

@mahmoudadel54 a couple of things more

Showing the download link of PDF at the navbar taps like:

please put it on the right with also a PDF icon on the left

Putting author title "GeoSolutionsGroup" instead of none

The second line should be the copyright. Please use the same you find in footer for now

[offtherailz]

Looking at the result (even if the background of the icon is wrong), I think that, in that menu, the icon is out of place.
It will be the only icon in the list, that looks quite strange.

So I suggest to drop this requirment, also because is not trivial to add it, and not so necessary.

@tdipisa can we avoid this requirement?

[tdipisa]

@ElenaGallo I understood you have enabled this for
https://docs.mapstore.geosolutionsgroup.com/en/master/

but that's not the usual latest endpoint used which is /latest indeed. Can you please fix?

[ElenaGallo]

@tdipisa now it is work also on latest endpoint

[tdipisa]

@ElenaGallo can you please completely remove the master one please?

[ElenaGallo]

@ElenaGallo can you please completely remove the master one please?

@tdipisa done

[tdipisa]

Last version

available at:

https://docs.mapstore.geosolutionsgroup.com/en/latest/
https://docs.mapstore.geosolutionsgroup.com/en/2024.01.xx/