script `build.py` - improve handling/reporting build.py

[mitzimorris]

trafficstars

Summary:

The build.py script doesn't have enough error handling. Improve both error handling in script, and provide more info on troubleshooting in repo README and wikil.

Description:

see discourse: https://discourse.mc-stan.org/t/error-compiling-docs-using-build-py/16526

Additional Information:

Provide any additional information here.

Current Version:

v2.18.0

[charlesm93]

Further suggestions: state the required R packages. In my experience, on top of the ones mentioned on ReadMe, the following packages were required: rstan, Bayesplot, kablextra, lubridate. Is there a way to check upfront the user has all the requisite packages installed? Can the user specify the libPath when running build.py?

[mikegilchrist]

Note the packages listed above should have 'bayesplot' instead of 'Bayesplot' and 'kableExtra" instead of 'kablextra'. I still can't get the functions-reference to build, however.

[bob-carpenter]

@mikegilchrist---Do you know what's blocking your functions reference build? I think there's a bit of extra make magic going on there to get all the indexes we need out for things like syntax highlighters.

[mikegilchrist]

I don't know what changed on my end, I do recall installing some fonts. I tried to find the Lucida_Fonts, but the link in the README.md indicated I had to purchase them, so I know I didn't do that. The fonts used in the pdf's I can build use "LM*" and "CharterBT*". pdfinfo gives the following details

.
.
.
Creator:         LaTeX via pandoc
Producer:        pdfTeX-1.40.24
.
.
.

Regardless, I can now build "html" and "pdf" versions of src/cmdstan-guide, src/functions-reference, and src/reference-manual , but can only successfully build the "html" version of src/stan-users-guide. Here's what I get when I try to build stan-users-guide as a pdf.

stan_docs] $ ./build.py 2 31 "stan-users-guide" "pdf"
render stan-users-guide as pdf
Command Rscript -e "bookdown::render_book('index.Rmd', output_format='bookdown::pdf_book')" failed
Traceback (most recent call last):
  File "./stan_docs/./build.py", line 128, in <module>
    main()
  File "./stan_docs/./build.py", line 124, in main
    make_docs(docspath, stan_version, doc, formats)
  File "./stan_docs/./build.py", line 55, in make_docs
    shexec(command)
  File "./stan_docs/./build.py", line 35, in shexec
    raise Exception(returncode)
Exception: 1

Not sure how to debug further, but would be happy to help.

[WardBrian]

We probably shouldn’t send stderr to /dev/null like we currently do in build.py

[bob-carpenter]

We probably shouldn’t send stderr to /dev/null like we currently do in build.py

Can you make that change, @WardBrian?

I verified the issue @mikegilchrist reported. I can build

• cmdstan html/pdf
• functions-reference html/pdf
• reference-manual html/pdf

but I cannot build

• stan-users-guide pdf -or- html

I get the same trace.

~/github/stan-dev/docs (master)$ python3 build.py 2 31 "stan-users-guide" "html" 
render stan-users-guide as html
Command Rscript -e "bookdown::render_book('index.Rmd', output_format='bookdown::gitbook')" failed
Traceback (most recent call last):
  File "/Users/bcarpenter/github/stan-dev/docs/build.py", line 128, in <module>
    main()
  File "/Users/bcarpenter/github/stan-dev/docs/build.py", line 124, in main
    make_docs(docspath, stan_version, doc, formats)
  File "/Users/bcarpenter/github/stan-dev/docs/build.py", line 64, in make_docs
    shexec(command)
  File "/Users/bcarpenter/github/stan-dev/docs/build.py", line 35, in shexec
    raise Exception(returncode)
Exception: 1

I'm using a MacBook Air with M2 chip and freshly installed R and pandoc.

[WardBrian]

Happy to make it print failures.

I can build all documents/formats locally without error, so I don't believe it is an issue of what is checked into the repo