From 42d875a41185b66ddc7399f87974c01e43ece88f Mon Sep 17 00:00:00 2001 From: Axel Kohlmeyer Date: Wed, 20 Apr 2022 15:02:00 -0400 Subject: [PATCH] add fasthtml target for faster testing of .rst to html translation --- doc/.gitignore | 2 +- doc/Makefile | 24 +++++++++++++++++++++--- doc/src/Build_manual.rst | 14 ++++++++++---- 3 files changed, 32 insertions(+), 8 deletions(-) diff --git a/doc/.gitignore b/doc/.gitignore index 7649fb34f1..7c953d2432 100644 --- a/doc/.gitignore +++ b/doc/.gitignore @@ -1,6 +1,6 @@ /old /html -/html-offline +/fasthtml /epub /latex /mathjax diff --git a/doc/Makefile b/doc/Makefile index a082018dfb..9372b24215 100644 --- a/doc/Makefile +++ b/doc/Makefile @@ -58,7 +58,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 +70,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 +84,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 +119,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 @(\ diff --git a/doc/src/Build_manual.rst b/doc/src/Build_manual.rst index 5dbefd8b6e..90633d0811 100644 --- a/doc/src/Build_manual.rst +++ b/doc/src/Build_manual.rst @@ -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 `_ 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