Skip to content

Commit a383199

Browse files
committed
doc: add note to README about Sphinx debugging
Problem: Sphinx, when run with make html, gives useless error messages, and we have no documentation on where to find the useful stuff, like tracebacks and Python output. Add a note to the README.
1 parent 63e85e3 commit a383199

File tree

1 file changed

+29
-0
lines changed

1 file changed

+29
-0
lines changed

doc/README.md

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -62,3 +62,32 @@ The tuple entry in the `man_pages` list specifies:
6262
It is possible for multiple man pages to be generated from a single source file.
6363
Simply create an entry for each man page you want generated.
6464
These entries can have the same file path, but different man page names.
65+
66+
### A Note on Sphinx Errors
67+
Sphinx writes helpful error logs to `TMPDIR`, so when debugging, if you're looking for a more useful error message than
68+
```
69+
make: *** [Makefile:1731: html] Error 2
70+
```
71+
look inside your `TMPDIR` and you will see a useful log file.
72+
```
73+
$ ls /tmp/elvis/
74+
sphinx-err-syr84dmk.log
75+
$
76+
$ cat /tmp/elvis/sphinx-err-syr84dmk.log
77+
# Sphinx version: 5.3.0
78+
# Python version: 3.6.8 (CPython)
79+
# Docutils version: 0.17.1 release
80+
# Jinja2 version: 3.0.3
81+
# Last messages:
82+
83+
# Loaded extensions:
84+
Traceback (most recent call last):
85+
File "/g/g0/elvis/k8senv/lib64/python3.6/site-packages/sphinx/cmd/build.py", line 280, in build_main
86+
args.pdb)
87+
File "/g/g0/elvis/k8senv/lib64/python3.6/site-packages/sphinx/application.py", line 237, in __init__
88+
self.config.setup(self)
89+
File "/g/g0/elvis/flux-core/doc/conf.py", line 156, in setup
90+
app.connect('builder-inited', run_apidoc)
91+
NameError: name 'run_apidoc' is not defined
92+
```
93+

0 commit comments

Comments
 (0)