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..58be62e712 100644 --- a/doc/Makefile +++ b/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; \ 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