Avoid using the prefix equation for tags and references. Actual equations within
the document are promoted with an equation- prefix. While using them is not a
problem. Just be aware that casual use of them may unexpectedly conflict with an
equation reference.
ERROR: ! Dimension too large
There may be a pdf that is too large. The default \maxdimen
is 16384 pts. To check the size of various pdf documents is to use
pdfinfo. In Ubuntu, the package poppler-utils contains
this tool.
The class graph for MOM__memory_8h__dep__incl.pdf gets very large
(22607 pts) and swamps pdflatex with a DOT_GRAPH_MAX_NODES set at
the maximum value of 10000. The default value, 50, works. A value
of 75 also worked in a recent test.
The generated PDF shows a Contents heading with no entries or is a blank page. This is indicative of excessive failures with latex. Latex generally requires multiple runs to properly create the table of contents, index, references, equations and pages.
Be very careful of string processing in python when handling
latex escaped math in equations. If a latex string for \theta is read in as
\\theta. Mishandling the string can cause the \\t to become a
tab (\t) and cause mahem with the processing.
Reference: string literals
Setup a virtual environment for processing:
python3 -m venv venv/mom6Doc
source venv/mom6Doc/bin/activate
# cd to the docs directory within the MOM6 repo
pip3 install -r requirements.txt
The deactivate command allows you to exit from the virtual environment.
NOTE: RTD will not upgrade the sphinx module if #egg= is specified in the requirements.txt file.
A useful commnad line tool for debugging sphinx and extensions is the python debugger. Add the following line to stop to any portion of the python code to create a break point.
import pdb; pdb.set_trace()
Run make html without redirection to a log file.
For only processing .dox files and some specific F90 files, edit and use the
Doxyfile_rtd_dox file. This limits the document processing to fewer files and
allows for rapid testing.
make clean; make html DOXYGEN_CONF=Doxyfile_rtd_dox UPDATEHTMLEQS=Y
The following example assumes a virtual environment as setup above using mom6Doc.
A similar environment is possible using anaconda.
$ source venv/mom6Doc/bin/activate
(mom6Doc) $ cd docs
(mom6Doc) $ make clean
(mom6Doc) $ make html >& _build/html_log.txt
(mom6Doc) $ make latexpdf >& _build/latex_log.txt
The last command may appear to hang. On error, latex will request input from the keyboard.
Press R and enter. This will keep latex running to completion or stop after 100 errors
are reached.
Once the documentation is built, you can use a web browser to look around in the _build
directory.
Python provides a way to quickly stand up a private web server for checking documentation. It requires knowledge of
the IP address if you are using a remote server, otherwise localhost should work.
You can start the server on any port. Port 8080 is shown here as an example.
python3 -m http.server 8080
After starting the server, you can browse to the known IP using http://IP:8080/ or if you are on the same
machine use http://localhost:8080/.