sage -docbuild: error building docs of single file #29651
Description
I tried a few different ways to build the docs of a single file, and got a few different errors. (But one of the methods works, so there is a workaround.) This is with sage 9.1.rc2 on Mac OS 10.15.3.
(1) My first attempt failed because 'DOT_SAGE' is not defined.
% sage --docbuild file=src/sage/plot/text.py pdf
Error building the documentation.
Traceback (most recent call last):
...
File "/Users/dmorris/Documents/misc/Programs/sage3/local/lib/python3.7/site-packages/sage_setup/docbuild/__init__.py", line 1165, in __init__
base_dir = os.path.join(DOT_SAGE, 'docbuild', module_name)
NameError: name 'DOT_SAGE' is not defined
(2) To avoid the need for DOT_SAGE, I gave an explicit build path. This worked better (it made pdf files of all of the plots), but failed with an AssertionError (and subsequent OSError): assert app.outdir.startswith(SAGE_DOC):
% sage --docbuild -o/Users/dmorris/tmp file=src/sage/plot/text.py pdf
...
[latex ] Exception occurred:
[latex ] File "/Users/dmorris/Documents/misc/Programs/sage3/src/sage_setup/docbuild/ext/multidocs.py", line 220, in citation_dir
[latex ] assert app.outdir.startswith(SAGE_DOC)
...
OSError: Exception occurred:
(3) To eliminate the AssertionError, I added a print statement to tell me the value of SAGE_DOC, and I used it for the build path. This worked! (The release number and author show up as "unknown" in the pdf file, but I am guessing that this is the expected behavior.)
% sage --docbuild -o/Users/dmorris/Documents/misc/Programs/sage3/local/share/doc/sage file=src/sage/plot/text.py pdf
[latex ] building [latex]: all documents
...
Output written on text.pdf (23 pages, 527224 bytes).
Transcript written on text.log.
=== TeX engine is 'pdfTeX'
Latexmk: Index file 'text.idx' was written
Latexmk: Log file says output to 'text.pdf'
Latexmk: All targets () are up-to-date
Build finished. The built documents can be found in /Users/dmorris/Documents/misc/Programs/sage3/local/share/doc/sage/text/output/pdf
(4) To save myself some typing, I tried again with a local path for the build directory, but got
RuntimeError: failed to run $MAKE all-pdf in local/share/doc/sage/text/output/latex
because
mv: rename text.pdf to local/share/doc/sage/text/output/pdf: No such file or directory`.
The directory actually did get created (but is empty). However, it seems that the local path fails because the $MAKE command is not running in my working directory (where I ran the sage --docbuild command). I don't know whether this is a bug, or the expected behavior.
% sage --docbuild -o local/share/doc/sage file=src/sage/plot/text.py pdf
[latex ] building [latex]: all documents
[latex ] updating environment: 1 added, 0 changed, 0 removed
[latex ] Merging environment/index files...
[latex ] ... done (0 todos, 1 index, 0 citations, 0 modules)
[latex ] WARNING: autodoc: failed to import module 'text'; the following exception was raised:
[latex ] No module named 'text'
[latex ] processing text.tex...index
[latex ] resolving references...
[latex ] writing... done
[latex ] copying TeX support files...
[latex ] done
[latex ] The LaTeX files are in local/share/doc/sage/text/output/latex.
[latex ] Run 'make' in that directory to run these through (pdf)latex
[latex ] (use `make latexpdf' here to do that automatically).
LaTeX file written to local/share/doc/sage/text/output/latex
latexmk -pdf -dvi- -ps- 'text.tex'
Latexmk: This is Latexmk, John Collins, 26 Dec. 2019, version: 4.67.
Latexmk: applying rule 'pdflatex'...
Rule 'pdflatex': The following rules & subrules became out-of-date:
'pdflatex'
------------
Run number 1 of rule 'pdflatex'
------------
------------
Running 'pdflatex -recorder "text.tex"'
------------
This is pdfTeX, Version 3.14159265-2.6-1.40.21 (TeX Live 2020) (preloaded format=pdflatex)
...
Transcript written in text.ilg.
Latexmk: applying rule 'pdflatex'...
Rule 'pdflatex': File changes, etc:
Changed files, or newly in use since previous run(s):
'text.aux'
'text.ind'
'text.out'
------------
Run number 2 of rule 'pdflatex'
------------
------------
Running 'pdflatex -recorder "text.tex"'
------------
This is pdfTeX, Version 3.14159265-2.6-1.40.21 (TeX Live 2020) (preloaded format=pdflatex)
...
Output written on text.pdf (4 pages, 7317 bytes).
Transcript written on text.log.
=== TeX engine is 'pdfTeX'
Latexmk: Index file 'text.idx' was written
Latexmk: Log file says output to 'text.pdf'
Latexmk: All targets () are up-to-date
mv: rename text.pdf to local/share/doc/sage/text/output/pdf: No such file or directory
Error building the documentation.
Traceback (most recent call last):
File "/Library/Frameworks/Python.framework/Versions/3.7/lib/python3.7/runpy.py", line 193, in _run_module_as_main
"__main__", mod_spec)
File "/Library/Frameworks/Python.framework/Versions/3.7/lib/python3.7/runpy.py", line 85, in _run_code
exec(code, run_globals)
File "/Users/dmorris/Documents/misc/Programs/sage3/local/lib/python3.7/site-packages/sage_setup/docbuild/__main__.py", line 2, in <module>
main()
File "/Users/dmorris/Documents/misc/Programs/sage3/local/lib/python3.7/site-packages/sage_setup/docbuild/__init__.py", line 1720, in main
builder()
File "/Users/dmorris/Documents/misc/Programs/sage3/local/lib/python3.7/site-packages/sage_setup/docbuild/__init__.py", line 252, in pdf
raise RuntimeError(error_message%(command, tex_dir))
RuntimeError: failed to run $MAKE all-pdf in local/share/doc/sage/text/output/latex
Component: build
Author: John Palmieri
Branch/Commit: b0310af
Reviewer: Matthias Koeppe
Issue created by migration from https://trac.sagemath.org/ticket/29651