Merge pull request #3222 from akohlmey/fasthtml
Add fasthtml target for faster testing of .rst to .html translation
This commit is contained in:
Axel Kohlmeyer
2
doc/.gitignore
vendored
2
doc/.gitignore
vendored
@ -1,6 +1,6 @@
|
||||
/old
|
||||
/html
|
||||
/html-offline
|
||||
/fasthtml
|
||||
/epub
|
||||
/latex
|
||||
/mathjax
|
||||
|
||||
38
doc/Makefile
38
doc/Makefile
@ -18,7 +18,6 @@ PYTHON = $(shell which python3)
|
||||
DOXYGEN = $(shell which doxygen)
|
||||
VIRTUALENV = virtualenv
|
||||
HAS_PYTHON3 = NO
|
||||
HAS_VIRTUALENV = NO
|
||||
HAS_DOXYGEN = NO
|
||||
HAS_PDFLATEX = NO
|
||||
|
||||
@ -30,16 +29,6 @@ ifeq ($(shell which doxygen >/dev/null 2>&1; echo $$?), 0)
|
||||
HAS_DOXYGEN = YES
|
||||
endif
|
||||
|
||||
ifeq ($(shell which virtualenv-3 >/dev/null 2>&1; echo $$?), 0)
|
||||
VIRTUALENV = virtualenv-3
|
||||
HAS_VIRTUALENV = YES
|
||||
endif
|
||||
|
||||
ifeq ($(shell which virtualenv >/dev/null 2>&1; echo $$?), 0)
|
||||
VIRTUALENV = virtualenv
|
||||
HAS_VIRTUALENV = YES
|
||||
endif
|
||||
|
||||
ifeq ($(shell which pdflatex >/dev/null 2>&1; echo $$?), 0)
|
||||
ifeq ($(shell which latexmk >/dev/null 2>&1; echo $$?), 0)
|
||||
HAS_PDFLATEX = YES
|
||||
@ -58,7 +47,7 @@ SPHINXEXTRA = -E -j $(shell $(PYTHON) -c 'import multiprocessing;print(multiproc
|
||||
# we only want to use explicitly listed files.
|
||||
DOXYFILES = $(shell sed -n -e 's/\#.*$$//' -e '/^ *INPUT \+=/,/^[A-Z_]\+ \+=/p' doxygen/Doxyfile.in | sed -e 's/@LAMMPS_SOURCE_DIR@/..\/src/g' -e 's/\\//g' -e 's/ \+/ /' -e 's/[A-Z_]\+ \+= *\(YES\|NO\|\)//')
|
||||
|
||||
.PHONY: help clean-all clean clean-spelling epub mobi rst html pdf spelling anchor_check style_check char_check xmlgen
|
||||
.PHONY: help clean-all clean clean-spelling epub mobi rst html pdf spelling anchor_check style_check char_check xmlgen fasthtml
|
||||
|
||||
# ------------------------------------------
|
||||
|
||||
@ -70,7 +59,8 @@ help:
|
||||
@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 " fasthtml approximate HTML page creation in fasthtml dir (for development)"
|
||||
@echo " clean remove all intermediate 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"
|
||||
@ -83,7 +73,7 @@ clean-all: clean
|
||||
rm -rf $(BUILDDIR)/docenv $(MATHJAX) $(BUILDDIR)/LAMMPS.mobi $(BUILDDIR)/LAMMPS.epub $(BUILDDIR)/Manual.pdf
|
||||
|
||||
clean: clean-spelling
|
||||
rm -rf $(BUILDDIR)/html $(BUILDDIR)/epub $(BUILDDIR)/latex $(BUILDDIR)/doctrees $(BUILDDIR)/doxygen/xml $(BUILDDIR)/doxygen-warn.log $(BUILDDIR)/doxygen/Doxyfile $(SPHINXCONFIG)/conf.py
|
||||
rm -rf $(BUILDDIR)/html $(BUILDDIR)/epub $(BUILDDIR)/latex $(BUILDDIR)/doctrees $(BUILDDIR)/doxygen/xml $(BUILDDIR)/doxygen-warn.log $(BUILDDIR)/doxygen/Doxyfile $(SPHINXCONFIG)/conf.py $(BUILDDIR)/fasthtml
|
||||
|
||||
clean-spelling:
|
||||
rm -rf $(BUILDDIR)/spelling
|
||||
@ -118,6 +108,23 @@ html: xmlgen $(VENV) $(SPHINXCONFIG)/conf.py $(ANCHORCHECK) $(MATHJAX)
|
||||
@rm -rf html/PDF/.[sg]*
|
||||
@echo "Build finished. The HTML pages are in doc/html."
|
||||
|
||||
fasthtml: xmlgen $(VENV) $(SPHINXCONFIG)/conf.py $(ANCHORCHECK) $(MATHJAX)
|
||||
@if [ "$(HAS_BASH)" == "NO" ] ; then echo "bash was not found at $(OSHELL)! Please use: $(MAKE) SHELL=/path/to/bash" 1>&2; exit 1; fi
|
||||
@$(MAKE) $(MFLAGS) -C graphviz all
|
||||
@mkdir -p fasthtml
|
||||
@(\
|
||||
. $(VENV)/bin/activate ; env PYTHONWARNINGS= \
|
||||
sphinx-build -j 4 -b html -c $(SPHINXCONFIG) -d $(BUILDDIR)/fasthtml/doctrees $(RSTDIR) fasthtml ;\
|
||||
deactivate ;\
|
||||
)
|
||||
@rm -rf fasthtml/_sources
|
||||
@rm -rf fasthtml/PDF
|
||||
@rm -rf fasthtml/USER
|
||||
@rm -rf fasthtml/JPG
|
||||
@cp -r src/PDF fasthtml/PDF
|
||||
@rm -rf fasthtml/PDF/.[sg]*
|
||||
@echo "Fast HTML build finished. The HTML pages are in doc/fasthtml."
|
||||
|
||||
spelling: xmlgen $(SPHINXCONFIG)/conf.py $(VENV) $(SPHINXCONFIG)/false_positives.txt
|
||||
@if [ "$(HAS_BASH)" == "NO" ] ; then echo "bash was not found at $(OSHELL)! Please use: $(MAKE) SHELL=/path/to/bash" 1>&2; exit 1; fi
|
||||
@(\
|
||||
@ -220,9 +227,8 @@ $(VENV):
|
||||
@if [ "$(HAS_BASH)" == "NO" ] ; then echo "bash was not found at $(OSHELL)! Please use: $(MAKE) SHELL=/path/to/bash" 1>&2; exit 1; fi
|
||||
@if [ "$(HAS_PYTHON3)" == "NO" ] ; then echo "python3 was not found! Please see README for further instructions" 1>&2; exit 1; fi
|
||||
@if [ "$(HAS_DOXYGEN)" == "NO" ] ; then echo "doxygen was not found! Please see README for further instructions" 1>&2; exit 1; fi
|
||||
@if [ "$(HAS_VIRTUALENV)" == "NO" ] ; then echo "virtualenv was not found! Please see README for further instructions" 1>&2; exit 1; fi
|
||||
@( \
|
||||
$(VIRTUALENV) -p $(PYTHON) $(VENV); \
|
||||
$(PYTHON) -m venv $(VENV); \
|
||||
. $(VENV)/bin/activate; \
|
||||
pip $(PIP_OPTIONS) install --upgrade pip; \
|
||||
pip $(PIP_OPTIONS) install -r $(BUILDDIR)/utils/requirements.txt; \
|
||||
|
||||
@ -78,11 +78,12 @@ folder. The following ``make`` commands are available:
|
||||
|
||||
make html # generate HTML in html dir using Sphinx
|
||||
make pdf # generate PDF as Manual.pdf using Sphinx and PDFLaTeX
|
||||
make fetch # fetch HTML pages and PDF files from LAMMPS website
|
||||
# and unpack into the html_www folder and Manual_www.pdf
|
||||
make epub # generate LAMMPS.epub in ePUB format using Sphinx
|
||||
make mobi # generate LAMMPS.mobi in MOBI format using ebook-convert
|
||||
|
||||
make fasthtml # generate approximate HTML in fasthtml dir using Sphinx
|
||||
# some Sphinx extensions do not work correctly with this
|
||||
|
||||
make clean # remove intermediate RST files created by HTML build
|
||||
make clean-all # remove entire build folder and any cached data
|
||||
|
||||
@ -193,8 +194,13 @@ folder need to be updated or new files added. These files are written in
|
||||
`reStructuredText <rst_>`_ markup for translation with the Sphinx tool.
|
||||
|
||||
Before contributing any documentation, please check that both the HTML
|
||||
and the PDF format documentation can translate without errors. Please also
|
||||
check the output to the console for any warnings or problems. There will
|
||||
and the PDF format documentation can translate without errors. During
|
||||
testing the html translation, you may use the ``make fasthtml`` command
|
||||
which does an approximate translation (i.e. not all Sphinx features and
|
||||
extensions will work), but runs very fast because it will only translate
|
||||
files that have been changed since the last ``make fasthtml`` command.
|
||||
|
||||
Please also check the output to the console for any warnings or problems. There will
|
||||
be multiple tests run automatically:
|
||||
|
||||
- A test for correctness of all anchor labels and their references
|
||||
|
||||
Reference in New Issue
Block a user