add ability to build an offline viewable html format manual in html-offline
This commit is contained in:
Axel Kohlmeyer
2
doc/.gitignore
vendored
2
doc/.gitignore
vendored
@ -1,6 +1,8 @@
|
||||
/old
|
||||
/html
|
||||
/html-offline
|
||||
/latex
|
||||
/mathjax
|
||||
/spelling
|
||||
/LAMMPS.epub
|
||||
/LAMMPS.mobi
|
||||
|
||||
63
doc/Makefile
63
doc/Makefile
@ -4,6 +4,7 @@ SHELL = /bin/bash
|
||||
BUILDDIR = ${CURDIR}
|
||||
RSTDIR = $(BUILDDIR)/src
|
||||
VENV = $(BUILDDIR)/docenv
|
||||
MATHJAX = $(BUILDDIR)/mathjax
|
||||
TXT2RST = $(VENV)/bin/txt2rst
|
||||
ANCHORCHECK = $(VENV)/bin/rst_anchor_check
|
||||
|
||||
@ -28,38 +29,36 @@ endif
|
||||
|
||||
SPHINXEXTRA = -j $(shell $(PYTHON) -c 'import multiprocessing;print(multiprocessing.cpu_count())')
|
||||
|
||||
.PHONY: help clean-all clean epub mobi rst html pdf venv spelling anchor_check style_check
|
||||
.PHONY: help clean-all clean clean-spelling epub mobi rst html html-offline pdf spelling anchor_check style_check
|
||||
|
||||
# ------------------------------------------
|
||||
|
||||
help:
|
||||
@echo "Please use \`make <target>' where <target> is one of"
|
||||
@echo " html create HTML doc pages in html dir"
|
||||
@echo " pdf create Developer.pdf and Manual.pdf in this dir"
|
||||
@echo " fetch fetch HTML and PDF files from LAMMPS web site"
|
||||
@echo " epub create ePUB format manual for e-book readers"
|
||||
@echo " mobi convert ePUB to MOBI format manual for e-book readers (e.g. Kindle)"
|
||||
@echo " html create HTML doc pages in html dir"
|
||||
@echo " html-offline create offline viewable HTML doc pages in html-offline dir"
|
||||
@echo " pdf create Developer.pdf and Manual.pdf in this dir"
|
||||
@echo " fetch fetch HTML and PDF files from LAMMPS web site"
|
||||
@echo " epub create ePUB format manual for e-book readers"
|
||||
@echo " mobi convert ePUB to MOBI format manual for e-book readers (e.g. Kindle)"
|
||||
@echo " (requires ebook-convert tool from calibre)"
|
||||
@echo " clean remove all intermediate RST files"
|
||||
@echo " clean-all reset the entire build environment"
|
||||
@echo " clean remove all intermediate RST files"
|
||||
@echo " clean-all reset the entire build environment"
|
||||
@echo " anchor_check scan for duplicate anchor labels"
|
||||
@echo " style_check check for complete and consistent style lists"
|
||||
@echo " spelling spell-check the manual"
|
||||
@echo " spelling spell-check the manual"
|
||||
|
||||
# ------------------------------------------
|
||||
|
||||
clean-all: clean
|
||||
rm -rf $(BUILDDIR)/docenv $(BUILDDIR)/doctrees
|
||||
rm -rf $(BUILDDIR)/docenv $(BUILDDIR)/doctrees $(BUILDDIR)/mathjax
|
||||
|
||||
clean:
|
||||
rm -rf html epub latex
|
||||
rm -rf spelling
|
||||
clean: clean-spelling
|
||||
rm -rf html epub latex html-offline
|
||||
|
||||
clean-spelling:
|
||||
rm -rf spelling
|
||||
|
||||
rst: clean $(ANCHORCHECK)
|
||||
|
||||
html: $(ANCHORCHECK)
|
||||
@(\
|
||||
. $(VENV)/bin/activate ;\
|
||||
@ -86,6 +85,37 @@ html: $(ANCHORCHECK)
|
||||
@rm -rf html/USER/*/*.[sg]*
|
||||
@echo "Build finished. The HTML pages are in doc/html."
|
||||
|
||||
|
||||
html-offline: $(ANCHORCHECK) $(MATHJAX)
|
||||
@(\
|
||||
. $(VENV)/bin/activate ;\
|
||||
sphinx-build $(SPHINXEXTRA) -D mathjax_path=mathjax/es5/tex-mml-chtml.js \
|
||||
-b html -c utils/sphinx-config -d $(BUILDDIR)/doctrees $(RSTDIR) html-offline ;\
|
||||
echo "############################################" ;\
|
||||
rst_anchor_check src/*.rst ;\
|
||||
env LC_ALL=C grep -n '[^ -~]' $(RSTDIR)/*.rst ;\
|
||||
python utils/check-styles.py -s ../src -d src ;\
|
||||
echo "############################################" ;\
|
||||
deactivate ;\
|
||||
)
|
||||
-rm html/searchindex.js
|
||||
@rm -rf html-offline/_sources
|
||||
@rm -rf html-offline/PDF
|
||||
@rm -rf html-offline/USER
|
||||
@rm -rf html-offline/JPG
|
||||
@cp -r src/PDF html-offline/PDF
|
||||
@cp -r src/USER html-offline/USER
|
||||
@mkdir -p html-offline/JPG
|
||||
@cp `grep -A2 '\.\. image::' src/*.rst | grep ':target:' | sed -e 's,.*:target: JPG/,src/JPG/,' | sort | uniq` html-offline/JPG/
|
||||
@rm -rf html-offline/PDF/.[sg]*
|
||||
@rm -rf html-offline/USER/.[sg]*
|
||||
@rm -rf html-offline/USER/*/.[sg]*
|
||||
@rm -rf html-offline/USER/*/*.[sg]*
|
||||
@echo "Build finished. The HTML pages are in doc/html-offline."
|
||||
@mkdir -p html-offline/_static/mathjax
|
||||
@cp -r $(MATHJAX)/es5 html-offline/_static/mathjax/
|
||||
|
||||
|
||||
spelling: utils/sphinx-config/false_positives.txt
|
||||
@(\
|
||||
. $(VENV)/bin/activate ;\
|
||||
@ -190,6 +220,9 @@ $(VENV):
|
||||
deactivate;\
|
||||
)
|
||||
|
||||
$(MATHJAX):
|
||||
@git clone https://github.com/mathjax/MathJax.git mathjax
|
||||
|
||||
$(TXT2RST) $(ANCHORCHECK): $(VENV)
|
||||
@( \
|
||||
. $(VENV)/bin/activate; \
|
||||
|
||||
@ -9,6 +9,7 @@ sub-directories and optionally 2 PDF files and 2 e-book format files:
|
||||
|
||||
src # content files for LAMMPS documentation
|
||||
html # HTML version of the LAMMPS manual (see html/Manual.html)
|
||||
html-offline # Offline viewable HTML version of the LAMMPS manual (see html/Manual.html)
|
||||
tools # tools and settings for building the documentation
|
||||
Manual.pdf # large PDF version of entire manual
|
||||
Developer.pdf # small PDF with info about how LAMMPS is structured
|
||||
@ -31,12 +32,20 @@ a. You can "fetch" the current HTML and PDF files from the LAMMPS web
|
||||
repository).
|
||||
|
||||
b. You can build the HTML and PDF files yourself, by typing "make html"
|
||||
followed by "make pdf". This requires various tools including
|
||||
Sphinx, which the build process will attempt to download and install
|
||||
automatically into a virtual environment in the folder doc/docenv, if
|
||||
not already available. See more details below. To generate the PDF
|
||||
version of the manual, additionally the PDFLaTeX software and several
|
||||
LaTeX packages are required.
|
||||
or "make html-offline" followed by "make pdf". This requires various
|
||||
tools including Sphinx, which the build process will attempt to
|
||||
download and install automatically into a virtual environment in the
|
||||
folder doc/docenv, if not already available. This download is
|
||||
required only once. The default HTML version in the html folder
|
||||
requires internet access to view the embedded math expressions. To
|
||||
be able to view the math offline, some extra data and javascript code
|
||||
needs to be downloaded and the HTML generation needs to be changed to
|
||||
reference them. When typing "make html-offline" this is done
|
||||
automatically. Same as for the sphinx tool, this download is
|
||||
required only once. After that also the processing of the
|
||||
documentation can be done without internet access. To generate the
|
||||
PDF version of the manual, additionally the PDFLaTeX software and
|
||||
several LaTeX packages are required.
|
||||
|
||||
----------
|
||||
|
||||
@ -50,6 +59,7 @@ the doc directory.
|
||||
Documentation Build Options:
|
||||
|
||||
make html # generate HTML in html dir using Sphinx
|
||||
make html-offline # generate offline viewable HTML in html-offline dir using Sphinx
|
||||
make pdf # generate 2 PDF files (Manual.pdf,Developer.pdf)
|
||||
# in doc dir via htmldoc and pdflatex
|
||||
make fetch # fetch HTML doc pages and 2 PDF files from web site
|
||||
|
||||
Reference in New Issue
Block a user