Documentation: Building PDF version of docs results in error

[kcondon]

l.3553 \begin{itemize}

@pdurbin I think you said you were familiar with this problem? Can you help?

! ==> Fatal error occurred, no output PDF file produced!
Transcript written on Dataverse.log.
make[1]: *** [Dataverse.pdf] Error 1
make[1]: Leaving directory `/var/lib/jenkins/workspace/guides.dataverse.org-rfi/doc/sphinx-guides/build/latex'
make: *** [latexpdf] Error 2
Build step 'Execute shell' marked build as failure
Finished: FAILURE

[pdurbin]

Here's more of the error as of a build from c81b7cf

! LaTeX Error: Too deeply nested.

See the LaTeX manual or LaTeX Companion for explanation.
Type  H <return>  for immediate help.
 ...                                              

l.3553 \begin{itemize}

? 
! Emergency stop.
 ...                                              

l.3553 \begin{itemize}

!  ==> Fatal error occurred, no output PDF file produced!
Transcript written on Dataverse.log.
make[1]: *** [Dataverse.pdf] Error 1
make[1]: Leaving directory `/var/lib/jenkins/workspace/guides.dataverse.org-rfi/doc/sphinx-guides/build/latex'
make: *** [latexpdf] Error 2
Build step 'Execute shell' marked build as failure
Finished: FAILURE

The last successful build was from 11ad621 and ended with this:

Chapter 7.
(./Dataverse.ind) [117] (./Dataverse.aux) )
(see the transcript file for additional information){/nfs/tools/apps/texlive/20
15/texmf-dist/fonts/enc/dvips/base/8r.enc}</nfs/tools/apps/texlive/2015/texmf-d
ist/fonts/type1/urw/courier/ucrb8a.pfb></nfs/tools/apps/texlive/2015/texmf-dist
/fonts/type1/urw/courier/ucrr8a.pfb></nfs/tools/apps/texlive/2015/texmf-dist/fo
nts/type1/urw/courier/ucrro8a.pfb></nfs/tools/apps/texlive/2015/texmf-dist/font
s/type1/urw/helvetic/uhvb8a.pfb></nfs/tools/apps/texlive/2015/texmf-dist/fonts/
type1/urw/helvetic/uhvbo8a.pfb></nfs/tools/apps/texlive/2015/texmf-dist/fonts/t
ype1/urw/times/utmb8a.pfb></nfs/tools/apps/texlive/2015/texmf-dist/fonts/type1/
urw/times/utmr8a.pfb></nfs/tools/apps/texlive/2015/texmf-dist/fonts/type1/urw/t
imes/utmri8a.pfb>
Output written on Dataverse.pdf (121 pages, 1162853 bytes).
Transcript written on Dataverse.log.
make[1]: Leaving directory `/var/lib/jenkins/workspace/guides.dataverse.org-rfi/doc/sphinx-guides/build/latex'
pdflatex finished; the PDF files are in build/latex.
+ cp build/latex/Dataverse.pdf build/html

So I guess something bad happened between 11ad621 (which shipped as part of 4.3.1) and c81b7cf (which is in the 2469-widgets branch). The 2469-widgets branch is pull request #3118 and the only change to the Sphinx source files so far was 873e341 so I'm guessing the problem was introduced there but I don't really know. As a workaround @kcondon and I decided to stop trying to build the PDF version since we don't even link to them yet per #2148.

@scolapasta I'm passing this to you for review.

[scolapasta]

Reverted the doc change from he widgets branch and it now works.

(we still need to work on the doc for widgets in general, so we'll make sure this continues to work when that is complete.

[mheppler]

Created a new issue to track the work needed for the widget documentation. #3147

[kcondon]

The error still happens with the most recent build. Passing back.

[scolapasta]

@pdurbin can you take a look with @mheppler and @eaquigley who have made doc changes and figure out what is causing this to break? Thanks.

[pdurbin]

@eaquigley is taking a look so I'll assign this to her. Something about nesting.

[kcondon]

There are also numerous latex build warnings leading up to the Too Deeply Nested error and most of those have to do with the Installation guide, shibboleth section but others too:

LaTeX Warning: Hyper reference `installation/shibboleth:shibboleth2-xml' on pag
e 63 undefined on input line 3595.

LaTeX Warning: Hyper reference `installation/shibboleth:specific-identity-provi
der-s-vs-identity-federation' on page 63 undefined on input line 3598.

! LaTeX Error: Too deeply nested.

[pdurbin]

Huh. If nesting in the Shib docs are a problem I do plan to revisit those docs as part of #2937.

The real problem here is that developers don't know how to create the PDF version of the guides on their laptops. I just tried this on my MacBook and wasn't able to figure out out quickly. If we ever make PDF versions of the guides a first class citizen (#2148) it will be considered a regression if a developer breaks the PDF. Developers will need to test locally before committing changes.

[mheppler]

Fixed nesting format issue in Shibboleth > Installation Guide breaking PDF creation of the guides. Also fixed other formatting, broken section link ref's and download file ref warnings.

Output written on Dataverse.pdf (147 pages, 1541202 bytes).
Transcript written on Dataverse.log.
pdflatex finished; the PDF files are in build/latex.

HTML, and latex/PDF should now all build with no warnings. But, epub still has a few minor warnings, but they do not break the build.

Code can be found in branch 3134-docs-build-errors. Which will be merged into the branch 3338-oauth-login.

[pdurbin]

@mheppler thanks! I added "Make it so PDFs can be built again (#3134). Start by merging 3134-docs-build-errors into 3338-oauth-login" to the checklist in #3338.

[pdurbin]

The fixes by @mheppler looked good. I only had to make one small change at 843e612.

In order to run make latexpdf I had to run brew cask install mactex. We should probably document this at http://guides.dataverse.org/en/4.6/developers/documentation.html so developers know how to even build a PDF on their Mac.

I just merged the 3134-docs-build-errors branch into into 3338-oauth-login so I'm going to delete the former. The latter should be used for QA and I'm moving this card there in https://waffle.io/IQSS/dataverse

[kcondon]

Works, closing.