From 3563d2f10de0da182455ff7b708b163f13e90438 Mon Sep 17 00:00:00 2001 From: Axel Kohlmeyer Date: Wed, 26 Feb 2020 15:55:20 -0500 Subject: [PATCH] remove references to html-offline and only produce the offline viewable html manual --- doc/Makefile | 43 +++------------------ doc/src/Manual_build.rst | 27 +++++-------- doc/utils/sphinx-config/conf.py | 3 ++ doc/utils/sphinx-config/false_positives.txt | 1 + 4 files changed, 20 insertions(+), 54 deletions(-) diff --git a/doc/Makefile b/doc/Makefile index 55402862e0..61fc2a0bc7 100644 --- a/doc/Makefile +++ b/doc/Makefile @@ -29,14 +29,13 @@ endif SPHINXEXTRA = -j $(shell $(PYTHON) -c 'import multiprocessing;print(multiprocessing.cpu_count())') -.PHONY: help clean-all clean clean-spelling epub mobi rst html html-offline pdf spelling anchor_check style_check +.PHONY: help clean-all clean clean-spelling epub mobi rst html pdf spelling anchor_check style_check # ------------------------------------------ help: @echo "Please use \`make ' where is one of" @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" @@ -55,12 +54,12 @@ clean-all: clean rm -rf $(BUILDDIR)/docenv $(BUILDDIR)/doctrees $(BUILDDIR)/mathjax clean: clean-spelling - rm -rf html epub latex html-offline + rm -rf html epub latex clean-spelling: rm -rf spelling -html: $(ANCHORCHECK) +html: $(ANCHORCHECK) $(MATHJAX) @(\ . $(VENV)/bin/activate ;\ sphinx-build $(SPHINXEXTRA) -b html -c utils/sphinx-config -d $(BUILDDIR)/doctrees $(RSTDIR) html ;\ @@ -85,40 +84,10 @@ html: $(ANCHORCHECK) @rm -rf html/USER/.[sg]* @rm -rf html/USER/*/.[sg]* @rm -rf html/USER/*/*.[sg]* + @mkdir -p html/_static/mathjax + @cp -r $(MATHJAX)/es5 html/_static/mathjax/ @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 ;\ - python utils/check-packages.py -s ../src -d src ;\ - 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: $(VENV) utils/sphinx-config/false_positives.txt @(\ . $(VENV)/bin/activate ;\ @@ -232,7 +201,7 @@ $(VENV): ) $(MATHJAX): - @git clone https://github.com/mathjax/MathJax.git mathjax + @git clone --depth 1 https://github.com/mathjax/MathJax.git mathjax $(TXT2RST) $(ANCHORCHECK): $(VENV) @( \ diff --git a/doc/src/Manual_build.rst b/doc/src/Manual_build.rst index 707f81d8da..26c32c0ccb 100644 --- a/doc/src/Manual_build.rst +++ b/doc/src/Manual_build.rst @@ -9,7 +9,6 @@ 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,21 +30,16 @@ a. You can "fetch" the current HTML and PDF files from the LAMMPS web changes (but your source code will not, unless you update your local repository). -b. You can build the HTML and PDF files yourself, by typing "make html" - 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 and its extensions, 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. +b. You can build the HTML or PDF files yourself, by typing "make html" + or "make pdf". This requires various tools including Sphinx, git, + and the MathJax javascript library, which the build process will attempt + to download automatically into a virtual environment in the folder + doc/docenv and the folder mathjax, respectively, if not already available. + This download is required only once, unless you type "make clean-all". + After that, viewing and processing of the documentation can be done + without internet access. To generate the PDF version of the manual, + the PDFLaTeX software and several LaTeX packages are required as well. + However, those cannot be installed automatically at the moment. ---------- @@ -59,7 +53,6 @@ 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 diff --git a/doc/utils/sphinx-config/conf.py b/doc/utils/sphinx-config/conf.py index 5f5642a622..235eed70de 100644 --- a/doc/utils/sphinx-config/conf.py +++ b/doc/utils/sphinx-config/conf.py @@ -210,6 +210,9 @@ if 'epub' in sys.argv: else: html_math_renderer = 'mathjax' +# use relative path for mathjax, so it is looked for in the +# html tree and the manual becomes readable when offline +mathjax_path = 'mathjax/es5/tex-mml-chtml.js' # -- Options for LaTeX output --------------------------------------------- latex_elements = { diff --git a/doc/utils/sphinx-config/false_positives.txt b/doc/utils/sphinx-config/false_positives.txt index 3e83477de6..a0a0535c71 100644 --- a/doc/utils/sphinx-config/false_positives.txt +++ b/doc/utils/sphinx-config/false_positives.txt @@ -1638,6 +1638,7 @@ Masuhiro Matchett Materias mathbf +mathjax matlab matplotlib Matsubara