Correcting the Sphinx documentation PDF build

[kuhlaid]

I am working on fixing the Sphinx documentation so builds of PDFs will succeed once again. The https://guides.dataverse.org/en/latest/admin/timers.html page in the documentation is at least one of the sources of Sphinx PDF builds currently failing. LaTeX seems to have a problem with multi-level lists in reStructuredText (.rst) files, such as:

* Alternatively, you can insert an ejb-jar.xml file into a provided Dataverse Software war file without building the application.

  * Check if there is already an ejb-jar.xml file in the war file 

    * jar tvf $DATAVERSE-WAR-FILENAME | grep ejb-jar.xml

      * if the response includes " WEB-INF/ejb-jar.xml", you will need to extract the ejb-jar.xml file for editing

        * jar xvf $DATAVERSE-WAR-FILENAME WEB-INF/ejb-jar.xml 

          * edit the extracted WEB-INF/ejb-jar.xml, following the sample file provided at ``/_static/admin/ejb-jar.xml``.

        * if the response is empty, create a WEB-INF directory and create en ejb-jar.xml file in it, following the sample file provided at ``/_static/admin/ejb-jar.xml``.

          * edit the parameters in the <schedule> section of the WEB-INF/ejb-jar.xml to suit your preferred schedule

For this page I receive a ! LaTeX Error: Too deeply nested. along with warnings such as LaTeX Warning: Hyper reference 'admin/timers:known-issues' on page 84 undefined on input line 5725. (which is referring to a line in the generated .tex file). Both, completely unhelpful LaTeX messages.

From testing it appears you are only able to include three sub-lists, or rather one root list item with three level below it:

* top level

  * second level

    * third level

      * fourth level (third sub-list)

Add a fifth level in the documentation and you break the PDF build:

* top level

  * second level

    * third level

      * fourth level (third sub-list)
      
        * fifth level (fourth sub-list), this will break the PDF build

Anyway, just wanted to give people a heads-up on this issue. I am looking into modifying the docs to do away with these deeply nested lists within the documentation and probably move it to a codeblock.

[pdurbin]

@kuhlaid we've definitely seen that "too deeply nested" error in the past (sorry, I should have given you a heads up about this). Yes, doing a little rewriting to avoid this sounds great. As part of your pull request, can you please also add a note to the future version of this page to explain how deep we can go? https://guides.dataverse.org/en/5.12.1/developers/documentation.html

Also, if it's possible to have make html fail with "for PDF building, you must nest less" (or whatever) that would be fantastic. Documentation writers aren't in the habit of building PDFs locally. If we can't do this, perhaps we can add on to https://github.com/IQSS/dataverse/blob/v5.12.1/.github/workflows/guides_build_sphinx.yml to have that GitHub Action try to build the PDF so we can tell right away when it's failing.

All this is to say, once we fix it, let's keep it fixed! 😄

Thanks for the legwork on this, @kuhlaid!! 🎉

[kuhlaid]

@pdurbin I have Dockerfile scripts to build the PDF documentation and then build the HTML documentation with the PDF included (shown in the included screenshot). I'm would vote for linking to the PDF in the HTML docs in some fashion (where the PDF resides is less important). I have my PDF located under the _static directory but could move it to root as you have it currently if that is preferred.

My question is, where do you want the Dockerfiles to reside? Currently I have them in the main codebase within sphinx-guides subfolders 'SphinxDocBuildPDF', 'SphinxDocBuildHtml', and 'SphinxDocLocalHtmlImage' (for building the PDF doc, the HTML docs, and an optional local Apache Docker container for testing the HTML docs in a browser - as shown in the screenshot below)

I want to make sure I write the documentation to reflect where the Dockerfiles can be found and get things organized in a reasonable fashion.

[pdurbin]

@kuhlaid this is great! Honestly, it's been a while but I think the guides are built by this or something similar: https://github.com/IQSS/dataverse-jenkins/blob/578b3b35accd57af333d644394c6b1acc8aed8b8/guides.dataverse.org.xml

Let me check in with @donsizemore and see how to proceed from here. I would assume we want the Dockerfile to reside here in the main repo? I'm not sure. 🤔

I'm a little confused though... you reduced the nesting? And got the PDF to build? And you plan to make a pull request? Thanks for working on this! 🎉

[donsizemore]

@pdurbin I'll wait to see the PR, but this can likely happen inside Jenkins per usual. GitHub workflow updates also welcome.

[kuhlaid]

Just checking in to get thoughts on PR #9306. Do you need anything else from me? - thank you

[pdurbin]

@kuhlaid hi! Just yesterday we pulled your PR into the current sprint! 🎉

However, I'm left wondering... would you be willing to swap it out for a fresh PR with the following characteristics:

• branched from develop
• smallest diff possible to the actual rst files (just remove hierarchy or whatever else is breaking the PDF)
• no PDF artifact in the branch itself (we'll build this with CI, probably the the GH Action you provided!)

Please let me know what you think. If you want, we can chat at https://chat.dataverse.org . Thanks!

[kuhlaid]

Thank you @pdurbin, let me see what I can do to trim down the PR. I'm cloning the latest develop branch and working from that. - cheers