add ability to build an offline viewable html format manual in html-offline (60cb4416) · Commits · 郑智淋 / lammps

doc/.gitignore

+2 −0

Original line number	Diff line number	Diff line
		/old
		/html
		/html-offline
		/latex
		/mathjax
		/spelling
		/LAMMPS.epub
		/LAMMPS.mobi

doc/Makefile

+48 −15

Original line number	Diff line number	Diff line
		@@ -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,13 +29,14 @@ 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 " 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"
		@@ -49,17 +51,14 @@ help:
		# ------------------------------------------

		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; \

doc/src/Manual_build.rst

+16 −6

Original line number	Diff line number	Diff line
		@@ -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

Admin message