Loading cmake/Modules/Documentation.cmake +54 −36 Original line number Diff line number Diff line Loading @@ -15,75 +15,93 @@ if(BUILD_DOC) endif() set(VIRTUALENV ${Python3_EXECUTABLE} -m virtualenv -p ${Python3_EXECUTABLE}) endif() find_package(Doxygen 1.8.10 REQUIRED) file(GLOB DOC_SOURCES ${LAMMPS_DOC_DIR}/src/[^.]*.rst) add_custom_command( OUTPUT docenv COMMAND ${VIRTUALENV} docenv ) set(DOCENV_BINARY_DIR ${CMAKE_BINARY_DIR}/docenv/bin) set(DOCENV_REQUIREMENTS_FILE ${LAMMPS_DOC_DIR}/utils/requirements.txt) set(SPHINX_CONFIG_DIR ${LAMMPS_DOC_DIR}/utils/sphinx-config) set(SPHINX_CONFIG_FILE_TEMPLATE ${SPHINX_CONFIG_DIR}/conf.py.in) set(SPHINX_STATIC_DIR ${SPHINX_CONFIG_DIR}/_static) # configuration and static files are copied to binary dir to avoid collisions with parallel builds set(DOC_BUILD_DIR ${CMAKE_CURRENT_BINARY_DIR}/doc) set(DOC_BUILD_CONFIG_FILE ${DOC_BUILD_DIR}/conf.py) set(DOC_BUILD_STATIC_DIR ${DOC_BUILD_DIR}/_static) set(DOXYGEN_BUILD_DIR ${DOC_BUILD_DIR}/doxygen) set(DOXYGEN_XML_DIR ${DOXYGEN_BUILD_DIR}/xml) # copy entire configuration folder to doc build directory # files in _static are automatically copied during sphinx-build, so no need to copy them individually file(COPY ${SPHINX_CONFIG_DIR}/ DESTINATION ${DOC_BUILD_DIR}) # configure paths in conf.py, since relative paths change when file is copied configure_file(${SPHINX_CONFIG_FILE_TEMPLATE} ${DOC_BUILD_CONFIG_FILE}) add_custom_command( OUTPUT requirements.txt DEPENDS docenv COMMAND ${CMAKE_COMMAND} -E copy ${LAMMPS_DOC_DIR}/utils/requirements.txt requirements.txt OUTPUT ${DOC_BUILD_DIR}/requirements.txt DEPENDS docenv ${DOCENV_REQUIREMENTS_FILE} COMMAND ${CMAKE_COMMAND} -E copy ${DOCENV_REQUIREMENTS_FILE} ${DOC_BUILD_DIR}/requirements.txt COMMAND ${DOCENV_BINARY_DIR}/pip install --upgrade pip COMMAND ${DOCENV_BINARY_DIR}/pip install --upgrade ${LAMMPS_DOC_DIR}/utils/converters COMMAND ${DOCENV_BINARY_DIR}/pip install --use-feature=2020-resolver -r requirements.txt --upgrade COMMAND ${DOCENV_BINARY_DIR}/pip install --use-feature=2020-resolver -r ${DOC_BUILD_DIR}/requirements.txt --upgrade ) # download mathjax distribution and unpack to folder "mathjax" if(NOT EXISTS ${CMAKE_CURRENT_BINARY_DIR}/mathjax/es5) if(NOT EXISTS ${DOC_BUILD_STATIC_DIR}/mathjax/es5) file(DOWNLOAD "https://github.com/mathjax/MathJax/archive/3.0.5.tar.gz" "${CMAKE_CURRENT_BINARY_DIR}/mathjax.tar.gz" EXPECTED_MD5 5d9d3799cce77a1a95eee6be04eb68e7) execute_process(COMMAND ${CMAKE_COMMAND} -E tar xzf mathjax.tar.gz WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}) file(GLOB MATHJAX_VERSION_DIR ${CMAKE_CURRENT_BINARY_DIR}/MathJax-*) execute_process(COMMAND ${CMAKE_COMMAND} -E rename ${MATHJAX_VERSION_DIR} ${CMAKE_CURRENT_BINARY_DIR}/mathjax) execute_process(COMMAND ${CMAKE_COMMAND} -E rename ${MATHJAX_VERSION_DIR} ${DOC_BUILD_STATIC_DIR}/mathjax) endif() file(MAKE_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/html/_static/mathjax) file(COPY ${CMAKE_CURRENT_BINARY_DIR}/mathjax/es5 DESTINATION ${CMAKE_CURRENT_BINARY_DIR}/html/_static/mathjax/) # for increased browser compatibility if(NOT EXISTS ${CMAKE_CURRENT_BINARY_DIR}/html/_static/polyfill.js) if(NOT EXISTS ${DOC_BUILD_STATIC_DIR}/polyfill.js) file(DOWNLOAD "https://polyfill.io/v3/polyfill.min.js?features=es6" "${CMAKE_CURRENT_BINARY_DIR}/html/_static/polyfill.js") "${DOC_BUILD_STATIC_DIR}/polyfill.js") endif() # note, this may run in parallel with other tasks, so we must not use multiple processes here # set up doxygen and add targets to run it file(MAKE_DIRECTORY ${DOXYGEN_BUILD_DIR}) file(COPY ${LAMMPS_DOC_DIR}/doxygen/lammps-logo.png DESTINATION ${DOXYGEN_BUILD_DIR}/lammps-logo.png) configure_file(${LAMMPS_DOC_DIR}/doxygen/Doxyfile.in ${DOXYGEN_BUILD_DIR}/Doxyfile) get_target_property(LAMMPS_SOURCES lammps SOURCES) add_custom_command( OUTPUT html DEPENDS ${DOC_SOURCES} docenv requirements.txt COMMAND ${DOCENV_BINARY_DIR}/sphinx-build -b html -c ${LAMMPS_DOC_DIR}/utils/sphinx-config -d ${CMAKE_BINARY_DIR}/doctrees ${LAMMPS_DOC_DIR}/src html COMMAND ${CMAKE_COMMAND} -E create_symlink Manual.html ${CMAKE_CURRENT_BINARY_DIR}/html/index.html OUTPUT ${DOXYGEN_XML_DIR}/index.xml DEPENDS ${DOC_SOURCES} ${LAMMPS_SOURCES} COMMAND Doxygen::doxygen ${DOXYGEN_BUILD_DIR}/Doxyfile WORKING_DIRECTORY ${DOXYGEN_BUILD_DIR} COMMAND ${CMAKE_COMMAND} -E touch ${DOXYGEN_XML_DIR}/run.stamp ) # copy selected image files to html output tree file(MAKE_DIRECTORY ${CMAKE_BINARY_DIR}/html/JPG) set(HTML_EXTRA_IMAGES balance_nonuniform.jpg balance_rcb.jpg balance_uniform.jpg bow_tutorial_01.png bow_tutorial_02.png bow_tutorial_03.png bow_tutorial_04.png bow_tutorial_05.png dump1.jpg dump2.jpg examples_mdpd.gif gran_funnel.png gran_mixer.png hop1.jpg hop2.jpg saed_ewald_intersect.jpg saed_mesh.jpg screenshot_atomeye.jpg screenshot_gl.jpg screenshot_pymol.jpg screenshot_vmd.jpg sinusoid.jpg xrd_mesh.jpg) set(HTML_IMAGE_TARGETS "") foreach(_IMG ${HTML_EXTRA_IMAGES}) string(PREPEND _IMG JPG/) list(APPEND HTML_IMAGE_TARGETS "${CMAKE_CURRENT_BINARY_DIR}/html/${_IMG}") if(EXISTS ${DOXYGEN_XML_DIR}/run.stamp) set(SPHINX_EXTRA_OPTS "-E") else() set(SPHINX_EXTRA_OPTS "") endif() add_custom_command( OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/html/${_IMG} DEPENDS ${LAMMPS_DOC_DIR}/src/${_IMG} ${CMAKE_CURRENT_BINARY_DIR}/html/JPG COMMAND ${CMAKE_COMMAND} -E copy ${LAMMPS_DOC_DIR}/src/${_IMG} ${CMAKE_BINARY_DIR}/html/${_IMG} OUTPUT html DEPENDS ${DOC_SOURCES} docenv ${DOC_BUILD_DIR}/requirements.txt ${DOXYGEN_XML_DIR}/index.xml ${BUILD_DOC_CONFIG_FILE} COMMAND ${DOCENV_BINARY_DIR}/sphinx-build ${SPHINX_EXTRA_OPTS} -b html -c ${DOC_BUILD_DIR} -d ${DOC_BUILD_DIR}/doctrees ${LAMMPS_DOC_DIR}/src ${DOC_BUILD_DIR}/html COMMAND ${CMAKE_COMMAND} -E create_symlink Manual.html ${DOC_BUILD_DIR}/html/index.html COMMAND ${CMAKE_COMMAND} -E copy_directory ${LAMMPS_DOC_DIR}/src/PDF ${DOC_BUILD_DIR}/html/PDF COMMAND ${CMAKE_COMMAND} -E remove -f ${DOXYGEN_XML_DIR}/run.stamp ) endforeach() add_custom_target( doc ALL DEPENDS html ${CMAKE_CURRENT_BINARY_DIR}/html/_static/mathjax/es5 ${HTML_IMAGE_TARGETS} DEPENDS html ${DOC_BUILD_STATIC_DIR}/mathjax/es5 SOURCES ${LAMMPS_DOC_DIR}/utils/requirements.txt ${DOC_SOURCES} ) install(DIRECTORY ${CMAKE_BINARY_DIR}/html DESTINATION ${CMAKE_INSTALL_DOCDIR}) install(DIRECTORY ${DOC_BUILD_DIR}/html DESTINATION ${CMAKE_INSTALL_DOCDIR}) endif() doc/.gitignore +7 −0 Original line number Diff line number Diff line /old /html /html-offline /epub /latex /mathjax /spelling Loading @@ -10,3 +11,9 @@ /Developer.pdf /doctrees /docenv /doxygen-warn.log /utils/sphinx-config/conf.py /doxygen/Doxyfile *.el /utils/sphinx-config/_static/mathjax /utils/sphinx-config/_static/polyfill.js doc/Makefile +70 −38 Original line number Diff line number Diff line Loading @@ -4,20 +4,28 @@ SHELL = /bin/bash BUILDDIR = ${CURDIR} RSTDIR = $(BUILDDIR)/src VENV = $(BUILDDIR)/docenv MATHJAX = $(BUILDDIR)/mathjax TXT2RST = $(VENV)/bin/txt2rst ANCHORCHECK = $(VENV)/bin/rst_anchor_check SPHINXCONFIG = $(BUILDDIR)/utils/sphinx-config MATHJAX = $(SPHINXCONFIG)/_static/mathjax POLYFILL = $(SPHINXCONFIG)/_static/polyfill.js PYTHON = $(shell which python3) DOXYGEN = $(shell which doxygen) VIRTUALENV = virtualenv HAS_PYTHON3 = NO HAS_VIRTUALENV = NO HAS_DOXYGEN = NO HAS_PDFLATEX = NO ifeq ($(shell which python3 >/dev/null 2>&1; echo $$?), 0) HAS_PYTHON3 = YES endif 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 Loading @@ -33,9 +41,13 @@ HAS_PDFLATEX = YES endif SPHINXEXTRA = -j $(shell $(PYTHON) -c 'import multiprocessing;print(multiprocessing.cpu_count())') SPHINXEXTRA = -j $(shell $(PYTHON) -c 'import multiprocessing;print(multiprocessing.cpu_count())') $(shell test -f $(BUILDDIR)/doxygen/xml/run.stamp && printf -- "-E") # grab list of sources from doxygen config file. # 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 .PHONY: help clean-all clean clean-spelling epub mobi rst html pdf spelling anchor_check style_check xmlgen # ------------------------------------------ Loading @@ -57,23 +69,32 @@ help: # ------------------------------------------ clean-all: clean rm -rf $(BUILDDIR)/docenv $(BUILDDIR)/doctrees $(BUILDDIR)/mathjax Manual.pdf Developer.pdf rm -rf $(BUILDDIR)/docenv $(MATHJAX) $(BUILDDIR)/LAMMPS.mobi $(BUILDDIR)/LAMMPS.epub $(BUILDDIR)/Manual.pdf $(BUILDDIR)/Developer.pdf clean: clean-spelling rm -rf html epub latex rm -rf $(BUILDDIR)/html $(BUILDDIR)/epub $(BUILDDIR)/latex $(BUILDDIR)/doctrees $(BUILDDIR)/doxygen/xml $(BUILDDIR)/doxygen-warn.log $(BUILDDIR)/doxygen/Doxyfile $(SPHINXCONFIG)/conf.py clean-spelling: rm -rf spelling rm -rf $(BUILDDIR)/spelling html: $(ANCHORCHECK) $(MATHJAX) $(SPHINXCONFIG)/conf.py: $(SPHINXCONFIG)/conf.py.in sed -e 's,@DOXYGEN_XML_DIR@,$(BUILDDIR)/doxygen/xml,g' \ -e 's,@LAMMPS_SOURCE_DIR@,$(BUILDDIR)/../src,g' \ -e 's,@LAMMPS_PYTHON_DIR@,$(BUILDDIR)/../python,g' \ -e 's,@LAMMPS_DOC_DIR@,$(BUILDDIR),g' $< > $@ html: xmlgen $(SPHINXCONFIG)/conf.py $(ANCHORCHECK) $(MATHJAX) $(POLYFILL) @$(MAKE) $(MFLAGS) -C graphviz all @(\ . $(VENV)/bin/activate ;\ sphinx-build $(SPHINXEXTRA) -b html -c utils/sphinx-config -d $(BUILDDIR)/doctrees $(RSTDIR) html ;\ . $(VENV)/bin/activate ; env PYTHONWARNINGS= \ sphinx-build $(SPHINXEXTRA) -b html -c $(SPHINXCONFIG) -d $(BUILDDIR)/doctrees $(RSTDIR) html ;\ ln -sf Manual.html html/index.html;\ rm -f $(BUILDDIR)/doxygen/xml/run.stamp;\ echo "############################################" ;\ rst_anchor_check src/*.rst ;\ python utils/check-packages.py -s ../src -d src ;\ python $(BUILDDIR)/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 ;\ python $(BUILDDIR)/utils/check-styles.py -s ../src -d src ;\ echo "############################################" ;\ deactivate ;\ ) Loading @@ -82,30 +103,28 @@ html: $(ANCHORCHECK) $(MATHJAX) @rm -rf html/USER @rm -rf html/JPG @cp -r src/PDF html/PDF @mkdir -p html/JPG @cp `grep -A2 '\.\. .*\(image\|figure\)::' src/*.rst | grep ':target: JPG' | sed -e 's,.*:target: JPG/,src/JPG/,' | sort | uniq` html/JPG/ @rm -rf html/PDF/.[sg]* @mkdir -p html/_static/mathjax @cp -r $(MATHJAX)/es5 html/_static/mathjax/ @echo "Build finished. The HTML pages are in doc/html." spelling: $(VENV) utils/sphinx-config/false_positives.txt spelling: xmlgen $(VENV) $(SPHINXCONFIG)/false_positives.txt @(\ . $(VENV)/bin/activate ;\ cp utils/sphinx-config/false_positives.txt $(RSTDIR)/ ; env PYTHONWARNINGS= \ sphinx-build -b spelling -c utils/sphinx-config -d $(BUILDDIR)/doctrees $(RSTDIR) spelling ;\ . $(VENV)/bin/activate ; env PYTHONWARNINGS= \ cp $(SPHINXCONFIG)/false_positives.txt $(RSTDIR)/ ; env PYTHONWARNINGS= \ sphinx-build -b spelling -c $(SPHINXCONFIG) -d $(BUILDDIR)/doctrees $(RSTDIR) spelling ;\ rm -f $(BUILDDIR)/doxygen/xml/run.stamp;\ deactivate ;\ ) @echo "Spell check finished." epub: $(VENV) epub: xmlgen $(VENV) $(SPHINXCONFIG)/conf.py $(ANCHORCHECK) @$(MAKE) $(MFLAGS) -C graphviz all @mkdir -p epub/JPG @rm -f LAMMPS.epub @cp src/JPG/lammps-logo.png epub/ @cp src/JPG/*.* epub/JPG @(\ . $(VENV)/bin/activate ;\ sphinx-build $(SPHINXEXTRA) -b epub -c utils/sphinx-config -d $(BUILDDIR)/doctrees $(RSTDIR) epub ;\ sphinx-build $(SPHINXEXTRA) -b epub -c $(SPHINXCONFIG) -d $(BUILDDIR)/doctrees $(RSTDIR) epub ;\ rm -f $(BUILDDIR)/doxygen/xml/run.stamp;\ deactivate ;\ ) @mv epub/LAMMPS.epub . Loading @@ -117,7 +136,8 @@ mobi: epub @ebook-convert LAMMPS.epub LAMMPS.mobi @echo "Conversion finished. The MOBI manual file is created." pdf: $(ANCHORCHECK) pdf: xmlgen $(VENV) $(SPHINXCONFIG)/conf.py $(ANCHORCHECK) @$(MAKE) $(MFLAGS) -C graphviz all @if [ "$(HAS_PDFLATEX)" == "NO" ] ; then echo "PDFLaTeX was not found! Please check README.md for further instructions" 1>&2; exit 1; fi @(\ cd src/Developer; \ Loading @@ -127,8 +147,9 @@ pdf: $(ANCHORCHECK) cd ../../; \ ) @(\ . $(VENV)/bin/activate ;\ sphinx-build $(SPHINXEXTRA) -b latex -c utils/sphinx-config -d $(BUILDDIR)/doctrees $(RSTDIR) latex ;\ . $(VENV)/bin/activate ; env PYTHONWARNINGS= \ sphinx-build $(SPHINXEXTRA) -b latex -c $(SPHINXCONFIG) -d $(BUILDDIR)/doctrees $(RSTDIR) latex ;\ rm -f $(BUILDDIR)/doxygen/xml/run.stamp;\ echo "############################################" ;\ rst_anchor_check src/*.rst ;\ python utils/check-packages.py -s ../src -d src ;\ Loading Loading @@ -185,21 +206,32 @@ package_check : $(VENV) deactivate ;\ ) xmlgen : doxygen/xml/index.xml doxygen/Doxyfile: doxygen/Doxyfile.in sed -e 's/@LAMMPS_SOURCE_DIR@/..\/..\/src/g' $< > $@ doxygen/xml/index.xml : $(VENV) doxygen/Doxyfile $(DOXYFILES) @(cd doxygen; $(DOXYGEN) Doxyfile && touch xml/run.stamp) # ------------------------------------------ $(VENV): @if [ "$(HAS_PYTHON3)" == "NO" ] ; then echo "Python3 was not found! Please check README.md for further instructions" 1>&2; exit 1; fi @if [ "$(HAS_VIRTUALENV)" == "NO" ] ; then echo "virtualenv was not found! Please check README.md for further instructions" 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); \ . $(VENV)/bin/activate; \ pip install --upgrade pip; \ pip install --use-feature=2020-resolver -r requirements.txt; \ pip install --use-feature=2020-resolver -r $(BUILDDIR)/utils/requirements.txt; \ deactivate;\ ) $(MATHJAX): @git clone --depth 1 https://github.com/mathjax/MathJax.git mathjax @git clone --depth 1 https://github.com/mathjax/MathJax.git $@ $(POLYFILL): $(MATHJAX) @curl -s -o $@ "https://polyfill.io/v3/polyfill.min.js?features=es6" $(TXT2RST) $(ANCHORCHECK): $(VENV) @( \ Loading doc/README +53 −101 Original line number Diff line number Diff line LAMMPS Documentation Depending on how you obtained LAMMPS, this directory has 2 or 3 sub-directories and optionally 2 PDF files and an ePUB file: Depending on how you obtained LAMMPS and whether you have built the manual yourself, this directory has a varying number of sub-directories and files. Here is a list with descriptions: README this file src content files for LAMMPS documentation html HTML version of the LAMMPS manual (see html/Manual.html) utils utilities 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 Manual.pdf PDF version of entire manual Developer.pdf PDF with info about how LAMMPS is structured LAMMPS.epub Manual in ePUB format If you downloaded LAMMPS as a tarball from the web site, all these directories and files should be included. If you downloaded LAMMPS from the public SVN or Git repositories, then the HTML and PDF files are not included. Instead you need to create them, in one of three ways: LAMMPS.mobi Manual in MOBI (Kindle) format lammps.1 man page for the lammps command msi2lmp.1 man page for the msi2lmp command mathjax code and fonts for rendering math in html doctree temporary data docenv python virtual environment for generating the manual doxygen Doxygen configuration and output .gitignore list of files and folders to be ignored by git doxygen-warn.log logfile with warnings from running doxygen and: github-development-workflow.md notes on the LAMMPS development workflow include-file-conventions.md notes on LAMMPS' include file conventions documentation_conventions.md notes on writing documentation for LAMMPS If you downloaded a LAMMPS tarball from lammps.sandia.gov, then the html folder and the PDF manual should be included. If you downloaded LAMMPS from GitHub then you either need to download them or build them. (a) You can "fetch" the current HTML and PDF files from the LAMMPS web site. Just type "make fetch". This should create a html_www dir and Manual_www.pdf/Developer_www.pdf files. Note that if new LAMMPS features have been added more recently than the date of your version, the fetched documentation will include those 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 by "make pdf", respectively. This requires various tools including the Python documentation processing tool Sphinx, which the build process will attempt to download and install on your system into a python virtual environment, if not already available. The PDF file will require a working LaTeX installation with several add-on packages in addition to the Python/Sphinx setup. See more details below. ---------------- The generation of all documentation is managed by the Makefile in this dir. Manual_www.pdf/Developer_www.pdf files. These files will always represent the latest published patch/development version of LAMMPS. Options: make html # generate HTML in html dir using Sphinx make pdf # generate 2 PDF files (Manual.pdf,Developer.pdf) # in this dir via Sphinx and PDFLaTeX make fetch # fetch HTML doc pages and 2 PDF files from web site # as a tarball and unpack into html dir and 2 PDFs make epub # generate LAMMPS.epub in ePUB format using Sphinx make clean # remove intermediate RST files created by HTML build make clean-all # remove entire build folder and any cached data (b) You can build the HTML and PDF files yourself, by typing "make html" or by "make pdf", respectively. This requires various tools and files. Some of them have to be installed (more on that below). For the rest the build process will attempt to download and install into a python virtual environment and local folders. ---------------- Installing prerequisites for HTML build To run the HTML documention build toolchain, Python 3 and virtualenv have to be installed. Here are instructions for common setups: # Ubuntu sudo apt-get install python-virtualenv # Fedora (up to version 21) # Red Hat Enterprise Linux or CentOS (up to version 7.x) sudo yum install python3-virtualenv # Fedora (since version 22) sudo dnf install python3-virtualenv # MacOS X Installing prerequisites for the documentation build ## Python 3 To run the HTML documention build toolchain, python 3.x, doxygen, git, and virtualenv have to be installed. Also internet access is initially required to download external files and tools. Download the latest Python 3 MacOS X package from https://www.python.org and install it. This will install both Python 3 and pip3. ## virtualenv Once Python 3 is installed, open a Terminal and type pip3 install virtualenv This will install virtualenv from the Python Package Index. ---------------- Installing prerequisites for PDF build Same as for HTML plus a compatible LaTeX installation with support for PDFLaTeX. Also the following LaTeX packages need to be installed (e.g. from texlive): Building the PDF format manual requires in addition a compatible LaTeX installation with support for PDFLaTeX and several add-on LaTeX packages installed. This includes: - amsmath - anysize - babel - capt-of - cmap Loading @@ -105,24 +68,13 @@ to be installed (e.g. from texlive): - tabulary - upquote - wrapfig ---------------- Installing prerequisites for epub build ## ePUB Same as for HTML. This uses the same tools and configuration files as the HTML tree. The ePUB format conversion currently does not support processing mathematical expressions via MathJAX, so there will be limitations on some pages. For the time being until this is resolved, building and using the PDF format file is recommended instead. For converting the generated ePUB file to a mobi format file (for e-book readers like Kindle, that cannot read ePUB), you also need to have the 'ebook-convert' tool from the "calibre" software installed. http://calibre-ebook.com/ You first create the ePUB file with 'make epub' and then do: ebook-convert LAMMPS.epub LAMMPS.mobi Building the EPUB format requires LaTeX installation with the same packages as for the PDF format plus the 'dvipng' command to convert the embedded math into images. The MOBI format is generated from the EPUB format file by using the tool 'ebook-convert' from the 'calibre' e-book management software (https://calibre-ebook.com). ---------------- More details this can be found in the manual itself. The online version is at: https://lammps.sandia.gov/doc/Manual_build.html Loading
cmake/Modules/Documentation.cmake +54 −36 Original line number Diff line number Diff line Loading @@ -15,75 +15,93 @@ if(BUILD_DOC) endif() set(VIRTUALENV ${Python3_EXECUTABLE} -m virtualenv -p ${Python3_EXECUTABLE}) endif() find_package(Doxygen 1.8.10 REQUIRED) file(GLOB DOC_SOURCES ${LAMMPS_DOC_DIR}/src/[^.]*.rst) add_custom_command( OUTPUT docenv COMMAND ${VIRTUALENV} docenv ) set(DOCENV_BINARY_DIR ${CMAKE_BINARY_DIR}/docenv/bin) set(DOCENV_REQUIREMENTS_FILE ${LAMMPS_DOC_DIR}/utils/requirements.txt) set(SPHINX_CONFIG_DIR ${LAMMPS_DOC_DIR}/utils/sphinx-config) set(SPHINX_CONFIG_FILE_TEMPLATE ${SPHINX_CONFIG_DIR}/conf.py.in) set(SPHINX_STATIC_DIR ${SPHINX_CONFIG_DIR}/_static) # configuration and static files are copied to binary dir to avoid collisions with parallel builds set(DOC_BUILD_DIR ${CMAKE_CURRENT_BINARY_DIR}/doc) set(DOC_BUILD_CONFIG_FILE ${DOC_BUILD_DIR}/conf.py) set(DOC_BUILD_STATIC_DIR ${DOC_BUILD_DIR}/_static) set(DOXYGEN_BUILD_DIR ${DOC_BUILD_DIR}/doxygen) set(DOXYGEN_XML_DIR ${DOXYGEN_BUILD_DIR}/xml) # copy entire configuration folder to doc build directory # files in _static are automatically copied during sphinx-build, so no need to copy them individually file(COPY ${SPHINX_CONFIG_DIR}/ DESTINATION ${DOC_BUILD_DIR}) # configure paths in conf.py, since relative paths change when file is copied configure_file(${SPHINX_CONFIG_FILE_TEMPLATE} ${DOC_BUILD_CONFIG_FILE}) add_custom_command( OUTPUT requirements.txt DEPENDS docenv COMMAND ${CMAKE_COMMAND} -E copy ${LAMMPS_DOC_DIR}/utils/requirements.txt requirements.txt OUTPUT ${DOC_BUILD_DIR}/requirements.txt DEPENDS docenv ${DOCENV_REQUIREMENTS_FILE} COMMAND ${CMAKE_COMMAND} -E copy ${DOCENV_REQUIREMENTS_FILE} ${DOC_BUILD_DIR}/requirements.txt COMMAND ${DOCENV_BINARY_DIR}/pip install --upgrade pip COMMAND ${DOCENV_BINARY_DIR}/pip install --upgrade ${LAMMPS_DOC_DIR}/utils/converters COMMAND ${DOCENV_BINARY_DIR}/pip install --use-feature=2020-resolver -r requirements.txt --upgrade COMMAND ${DOCENV_BINARY_DIR}/pip install --use-feature=2020-resolver -r ${DOC_BUILD_DIR}/requirements.txt --upgrade ) # download mathjax distribution and unpack to folder "mathjax" if(NOT EXISTS ${CMAKE_CURRENT_BINARY_DIR}/mathjax/es5) if(NOT EXISTS ${DOC_BUILD_STATIC_DIR}/mathjax/es5) file(DOWNLOAD "https://github.com/mathjax/MathJax/archive/3.0.5.tar.gz" "${CMAKE_CURRENT_BINARY_DIR}/mathjax.tar.gz" EXPECTED_MD5 5d9d3799cce77a1a95eee6be04eb68e7) execute_process(COMMAND ${CMAKE_COMMAND} -E tar xzf mathjax.tar.gz WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}) file(GLOB MATHJAX_VERSION_DIR ${CMAKE_CURRENT_BINARY_DIR}/MathJax-*) execute_process(COMMAND ${CMAKE_COMMAND} -E rename ${MATHJAX_VERSION_DIR} ${CMAKE_CURRENT_BINARY_DIR}/mathjax) execute_process(COMMAND ${CMAKE_COMMAND} -E rename ${MATHJAX_VERSION_DIR} ${DOC_BUILD_STATIC_DIR}/mathjax) endif() file(MAKE_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/html/_static/mathjax) file(COPY ${CMAKE_CURRENT_BINARY_DIR}/mathjax/es5 DESTINATION ${CMAKE_CURRENT_BINARY_DIR}/html/_static/mathjax/) # for increased browser compatibility if(NOT EXISTS ${CMAKE_CURRENT_BINARY_DIR}/html/_static/polyfill.js) if(NOT EXISTS ${DOC_BUILD_STATIC_DIR}/polyfill.js) file(DOWNLOAD "https://polyfill.io/v3/polyfill.min.js?features=es6" "${CMAKE_CURRENT_BINARY_DIR}/html/_static/polyfill.js") "${DOC_BUILD_STATIC_DIR}/polyfill.js") endif() # note, this may run in parallel with other tasks, so we must not use multiple processes here # set up doxygen and add targets to run it file(MAKE_DIRECTORY ${DOXYGEN_BUILD_DIR}) file(COPY ${LAMMPS_DOC_DIR}/doxygen/lammps-logo.png DESTINATION ${DOXYGEN_BUILD_DIR}/lammps-logo.png) configure_file(${LAMMPS_DOC_DIR}/doxygen/Doxyfile.in ${DOXYGEN_BUILD_DIR}/Doxyfile) get_target_property(LAMMPS_SOURCES lammps SOURCES) add_custom_command( OUTPUT html DEPENDS ${DOC_SOURCES} docenv requirements.txt COMMAND ${DOCENV_BINARY_DIR}/sphinx-build -b html -c ${LAMMPS_DOC_DIR}/utils/sphinx-config -d ${CMAKE_BINARY_DIR}/doctrees ${LAMMPS_DOC_DIR}/src html COMMAND ${CMAKE_COMMAND} -E create_symlink Manual.html ${CMAKE_CURRENT_BINARY_DIR}/html/index.html OUTPUT ${DOXYGEN_XML_DIR}/index.xml DEPENDS ${DOC_SOURCES} ${LAMMPS_SOURCES} COMMAND Doxygen::doxygen ${DOXYGEN_BUILD_DIR}/Doxyfile WORKING_DIRECTORY ${DOXYGEN_BUILD_DIR} COMMAND ${CMAKE_COMMAND} -E touch ${DOXYGEN_XML_DIR}/run.stamp ) # copy selected image files to html output tree file(MAKE_DIRECTORY ${CMAKE_BINARY_DIR}/html/JPG) set(HTML_EXTRA_IMAGES balance_nonuniform.jpg balance_rcb.jpg balance_uniform.jpg bow_tutorial_01.png bow_tutorial_02.png bow_tutorial_03.png bow_tutorial_04.png bow_tutorial_05.png dump1.jpg dump2.jpg examples_mdpd.gif gran_funnel.png gran_mixer.png hop1.jpg hop2.jpg saed_ewald_intersect.jpg saed_mesh.jpg screenshot_atomeye.jpg screenshot_gl.jpg screenshot_pymol.jpg screenshot_vmd.jpg sinusoid.jpg xrd_mesh.jpg) set(HTML_IMAGE_TARGETS "") foreach(_IMG ${HTML_EXTRA_IMAGES}) string(PREPEND _IMG JPG/) list(APPEND HTML_IMAGE_TARGETS "${CMAKE_CURRENT_BINARY_DIR}/html/${_IMG}") if(EXISTS ${DOXYGEN_XML_DIR}/run.stamp) set(SPHINX_EXTRA_OPTS "-E") else() set(SPHINX_EXTRA_OPTS "") endif() add_custom_command( OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/html/${_IMG} DEPENDS ${LAMMPS_DOC_DIR}/src/${_IMG} ${CMAKE_CURRENT_BINARY_DIR}/html/JPG COMMAND ${CMAKE_COMMAND} -E copy ${LAMMPS_DOC_DIR}/src/${_IMG} ${CMAKE_BINARY_DIR}/html/${_IMG} OUTPUT html DEPENDS ${DOC_SOURCES} docenv ${DOC_BUILD_DIR}/requirements.txt ${DOXYGEN_XML_DIR}/index.xml ${BUILD_DOC_CONFIG_FILE} COMMAND ${DOCENV_BINARY_DIR}/sphinx-build ${SPHINX_EXTRA_OPTS} -b html -c ${DOC_BUILD_DIR} -d ${DOC_BUILD_DIR}/doctrees ${LAMMPS_DOC_DIR}/src ${DOC_BUILD_DIR}/html COMMAND ${CMAKE_COMMAND} -E create_symlink Manual.html ${DOC_BUILD_DIR}/html/index.html COMMAND ${CMAKE_COMMAND} -E copy_directory ${LAMMPS_DOC_DIR}/src/PDF ${DOC_BUILD_DIR}/html/PDF COMMAND ${CMAKE_COMMAND} -E remove -f ${DOXYGEN_XML_DIR}/run.stamp ) endforeach() add_custom_target( doc ALL DEPENDS html ${CMAKE_CURRENT_BINARY_DIR}/html/_static/mathjax/es5 ${HTML_IMAGE_TARGETS} DEPENDS html ${DOC_BUILD_STATIC_DIR}/mathjax/es5 SOURCES ${LAMMPS_DOC_DIR}/utils/requirements.txt ${DOC_SOURCES} ) install(DIRECTORY ${CMAKE_BINARY_DIR}/html DESTINATION ${CMAKE_INSTALL_DOCDIR}) install(DIRECTORY ${DOC_BUILD_DIR}/html DESTINATION ${CMAKE_INSTALL_DOCDIR}) endif()
doc/.gitignore +7 −0 Original line number Diff line number Diff line /old /html /html-offline /epub /latex /mathjax /spelling Loading @@ -10,3 +11,9 @@ /Developer.pdf /doctrees /docenv /doxygen-warn.log /utils/sphinx-config/conf.py /doxygen/Doxyfile *.el /utils/sphinx-config/_static/mathjax /utils/sphinx-config/_static/polyfill.js
doc/Makefile +70 −38 Original line number Diff line number Diff line Loading @@ -4,20 +4,28 @@ SHELL = /bin/bash BUILDDIR = ${CURDIR} RSTDIR = $(BUILDDIR)/src VENV = $(BUILDDIR)/docenv MATHJAX = $(BUILDDIR)/mathjax TXT2RST = $(VENV)/bin/txt2rst ANCHORCHECK = $(VENV)/bin/rst_anchor_check SPHINXCONFIG = $(BUILDDIR)/utils/sphinx-config MATHJAX = $(SPHINXCONFIG)/_static/mathjax POLYFILL = $(SPHINXCONFIG)/_static/polyfill.js PYTHON = $(shell which python3) DOXYGEN = $(shell which doxygen) VIRTUALENV = virtualenv HAS_PYTHON3 = NO HAS_VIRTUALENV = NO HAS_DOXYGEN = NO HAS_PDFLATEX = NO ifeq ($(shell which python3 >/dev/null 2>&1; echo $$?), 0) HAS_PYTHON3 = YES endif 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 Loading @@ -33,9 +41,13 @@ HAS_PDFLATEX = YES endif SPHINXEXTRA = -j $(shell $(PYTHON) -c 'import multiprocessing;print(multiprocessing.cpu_count())') SPHINXEXTRA = -j $(shell $(PYTHON) -c 'import multiprocessing;print(multiprocessing.cpu_count())') $(shell test -f $(BUILDDIR)/doxygen/xml/run.stamp && printf -- "-E") # grab list of sources from doxygen config file. # 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 .PHONY: help clean-all clean clean-spelling epub mobi rst html pdf spelling anchor_check style_check xmlgen # ------------------------------------------ Loading @@ -57,23 +69,32 @@ help: # ------------------------------------------ clean-all: clean rm -rf $(BUILDDIR)/docenv $(BUILDDIR)/doctrees $(BUILDDIR)/mathjax Manual.pdf Developer.pdf rm -rf $(BUILDDIR)/docenv $(MATHJAX) $(BUILDDIR)/LAMMPS.mobi $(BUILDDIR)/LAMMPS.epub $(BUILDDIR)/Manual.pdf $(BUILDDIR)/Developer.pdf clean: clean-spelling rm -rf html epub latex rm -rf $(BUILDDIR)/html $(BUILDDIR)/epub $(BUILDDIR)/latex $(BUILDDIR)/doctrees $(BUILDDIR)/doxygen/xml $(BUILDDIR)/doxygen-warn.log $(BUILDDIR)/doxygen/Doxyfile $(SPHINXCONFIG)/conf.py clean-spelling: rm -rf spelling rm -rf $(BUILDDIR)/spelling html: $(ANCHORCHECK) $(MATHJAX) $(SPHINXCONFIG)/conf.py: $(SPHINXCONFIG)/conf.py.in sed -e 's,@DOXYGEN_XML_DIR@,$(BUILDDIR)/doxygen/xml,g' \ -e 's,@LAMMPS_SOURCE_DIR@,$(BUILDDIR)/../src,g' \ -e 's,@LAMMPS_PYTHON_DIR@,$(BUILDDIR)/../python,g' \ -e 's,@LAMMPS_DOC_DIR@,$(BUILDDIR),g' $< > $@ html: xmlgen $(SPHINXCONFIG)/conf.py $(ANCHORCHECK) $(MATHJAX) $(POLYFILL) @$(MAKE) $(MFLAGS) -C graphviz all @(\ . $(VENV)/bin/activate ;\ sphinx-build $(SPHINXEXTRA) -b html -c utils/sphinx-config -d $(BUILDDIR)/doctrees $(RSTDIR) html ;\ . $(VENV)/bin/activate ; env PYTHONWARNINGS= \ sphinx-build $(SPHINXEXTRA) -b html -c $(SPHINXCONFIG) -d $(BUILDDIR)/doctrees $(RSTDIR) html ;\ ln -sf Manual.html html/index.html;\ rm -f $(BUILDDIR)/doxygen/xml/run.stamp;\ echo "############################################" ;\ rst_anchor_check src/*.rst ;\ python utils/check-packages.py -s ../src -d src ;\ python $(BUILDDIR)/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 ;\ python $(BUILDDIR)/utils/check-styles.py -s ../src -d src ;\ echo "############################################" ;\ deactivate ;\ ) Loading @@ -82,30 +103,28 @@ html: $(ANCHORCHECK) $(MATHJAX) @rm -rf html/USER @rm -rf html/JPG @cp -r src/PDF html/PDF @mkdir -p html/JPG @cp `grep -A2 '\.\. .*\(image\|figure\)::' src/*.rst | grep ':target: JPG' | sed -e 's,.*:target: JPG/,src/JPG/,' | sort | uniq` html/JPG/ @rm -rf html/PDF/.[sg]* @mkdir -p html/_static/mathjax @cp -r $(MATHJAX)/es5 html/_static/mathjax/ @echo "Build finished. The HTML pages are in doc/html." spelling: $(VENV) utils/sphinx-config/false_positives.txt spelling: xmlgen $(VENV) $(SPHINXCONFIG)/false_positives.txt @(\ . $(VENV)/bin/activate ;\ cp utils/sphinx-config/false_positives.txt $(RSTDIR)/ ; env PYTHONWARNINGS= \ sphinx-build -b spelling -c utils/sphinx-config -d $(BUILDDIR)/doctrees $(RSTDIR) spelling ;\ . $(VENV)/bin/activate ; env PYTHONWARNINGS= \ cp $(SPHINXCONFIG)/false_positives.txt $(RSTDIR)/ ; env PYTHONWARNINGS= \ sphinx-build -b spelling -c $(SPHINXCONFIG) -d $(BUILDDIR)/doctrees $(RSTDIR) spelling ;\ rm -f $(BUILDDIR)/doxygen/xml/run.stamp;\ deactivate ;\ ) @echo "Spell check finished." epub: $(VENV) epub: xmlgen $(VENV) $(SPHINXCONFIG)/conf.py $(ANCHORCHECK) @$(MAKE) $(MFLAGS) -C graphviz all @mkdir -p epub/JPG @rm -f LAMMPS.epub @cp src/JPG/lammps-logo.png epub/ @cp src/JPG/*.* epub/JPG @(\ . $(VENV)/bin/activate ;\ sphinx-build $(SPHINXEXTRA) -b epub -c utils/sphinx-config -d $(BUILDDIR)/doctrees $(RSTDIR) epub ;\ sphinx-build $(SPHINXEXTRA) -b epub -c $(SPHINXCONFIG) -d $(BUILDDIR)/doctrees $(RSTDIR) epub ;\ rm -f $(BUILDDIR)/doxygen/xml/run.stamp;\ deactivate ;\ ) @mv epub/LAMMPS.epub . Loading @@ -117,7 +136,8 @@ mobi: epub @ebook-convert LAMMPS.epub LAMMPS.mobi @echo "Conversion finished. The MOBI manual file is created." pdf: $(ANCHORCHECK) pdf: xmlgen $(VENV) $(SPHINXCONFIG)/conf.py $(ANCHORCHECK) @$(MAKE) $(MFLAGS) -C graphviz all @if [ "$(HAS_PDFLATEX)" == "NO" ] ; then echo "PDFLaTeX was not found! Please check README.md for further instructions" 1>&2; exit 1; fi @(\ cd src/Developer; \ Loading @@ -127,8 +147,9 @@ pdf: $(ANCHORCHECK) cd ../../; \ ) @(\ . $(VENV)/bin/activate ;\ sphinx-build $(SPHINXEXTRA) -b latex -c utils/sphinx-config -d $(BUILDDIR)/doctrees $(RSTDIR) latex ;\ . $(VENV)/bin/activate ; env PYTHONWARNINGS= \ sphinx-build $(SPHINXEXTRA) -b latex -c $(SPHINXCONFIG) -d $(BUILDDIR)/doctrees $(RSTDIR) latex ;\ rm -f $(BUILDDIR)/doxygen/xml/run.stamp;\ echo "############################################" ;\ rst_anchor_check src/*.rst ;\ python utils/check-packages.py -s ../src -d src ;\ Loading Loading @@ -185,21 +206,32 @@ package_check : $(VENV) deactivate ;\ ) xmlgen : doxygen/xml/index.xml doxygen/Doxyfile: doxygen/Doxyfile.in sed -e 's/@LAMMPS_SOURCE_DIR@/..\/..\/src/g' $< > $@ doxygen/xml/index.xml : $(VENV) doxygen/Doxyfile $(DOXYFILES) @(cd doxygen; $(DOXYGEN) Doxyfile && touch xml/run.stamp) # ------------------------------------------ $(VENV): @if [ "$(HAS_PYTHON3)" == "NO" ] ; then echo "Python3 was not found! Please check README.md for further instructions" 1>&2; exit 1; fi @if [ "$(HAS_VIRTUALENV)" == "NO" ] ; then echo "virtualenv was not found! Please check README.md for further instructions" 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); \ . $(VENV)/bin/activate; \ pip install --upgrade pip; \ pip install --use-feature=2020-resolver -r requirements.txt; \ pip install --use-feature=2020-resolver -r $(BUILDDIR)/utils/requirements.txt; \ deactivate;\ ) $(MATHJAX): @git clone --depth 1 https://github.com/mathjax/MathJax.git mathjax @git clone --depth 1 https://github.com/mathjax/MathJax.git $@ $(POLYFILL): $(MATHJAX) @curl -s -o $@ "https://polyfill.io/v3/polyfill.min.js?features=es6" $(TXT2RST) $(ANCHORCHECK): $(VENV) @( \ Loading
doc/README +53 −101 Original line number Diff line number Diff line LAMMPS Documentation Depending on how you obtained LAMMPS, this directory has 2 or 3 sub-directories and optionally 2 PDF files and an ePUB file: Depending on how you obtained LAMMPS and whether you have built the manual yourself, this directory has a varying number of sub-directories and files. Here is a list with descriptions: README this file src content files for LAMMPS documentation html HTML version of the LAMMPS manual (see html/Manual.html) utils utilities 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 Manual.pdf PDF version of entire manual Developer.pdf PDF with info about how LAMMPS is structured LAMMPS.epub Manual in ePUB format If you downloaded LAMMPS as a tarball from the web site, all these directories and files should be included. If you downloaded LAMMPS from the public SVN or Git repositories, then the HTML and PDF files are not included. Instead you need to create them, in one of three ways: LAMMPS.mobi Manual in MOBI (Kindle) format lammps.1 man page for the lammps command msi2lmp.1 man page for the msi2lmp command mathjax code and fonts for rendering math in html doctree temporary data docenv python virtual environment for generating the manual doxygen Doxygen configuration and output .gitignore list of files and folders to be ignored by git doxygen-warn.log logfile with warnings from running doxygen and: github-development-workflow.md notes on the LAMMPS development workflow include-file-conventions.md notes on LAMMPS' include file conventions documentation_conventions.md notes on writing documentation for LAMMPS If you downloaded a LAMMPS tarball from lammps.sandia.gov, then the html folder and the PDF manual should be included. If you downloaded LAMMPS from GitHub then you either need to download them or build them. (a) You can "fetch" the current HTML and PDF files from the LAMMPS web site. Just type "make fetch". This should create a html_www dir and Manual_www.pdf/Developer_www.pdf files. Note that if new LAMMPS features have been added more recently than the date of your version, the fetched documentation will include those 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 by "make pdf", respectively. This requires various tools including the Python documentation processing tool Sphinx, which the build process will attempt to download and install on your system into a python virtual environment, if not already available. The PDF file will require a working LaTeX installation with several add-on packages in addition to the Python/Sphinx setup. See more details below. ---------------- The generation of all documentation is managed by the Makefile in this dir. Manual_www.pdf/Developer_www.pdf files. These files will always represent the latest published patch/development version of LAMMPS. Options: make html # generate HTML in html dir using Sphinx make pdf # generate 2 PDF files (Manual.pdf,Developer.pdf) # in this dir via Sphinx and PDFLaTeX make fetch # fetch HTML doc pages and 2 PDF files from web site # as a tarball and unpack into html dir and 2 PDFs make epub # generate LAMMPS.epub in ePUB format using Sphinx make clean # remove intermediate RST files created by HTML build make clean-all # remove entire build folder and any cached data (b) You can build the HTML and PDF files yourself, by typing "make html" or by "make pdf", respectively. This requires various tools and files. Some of them have to be installed (more on that below). For the rest the build process will attempt to download and install into a python virtual environment and local folders. ---------------- Installing prerequisites for HTML build To run the HTML documention build toolchain, Python 3 and virtualenv have to be installed. Here are instructions for common setups: # Ubuntu sudo apt-get install python-virtualenv # Fedora (up to version 21) # Red Hat Enterprise Linux or CentOS (up to version 7.x) sudo yum install python3-virtualenv # Fedora (since version 22) sudo dnf install python3-virtualenv # MacOS X Installing prerequisites for the documentation build ## Python 3 To run the HTML documention build toolchain, python 3.x, doxygen, git, and virtualenv have to be installed. Also internet access is initially required to download external files and tools. Download the latest Python 3 MacOS X package from https://www.python.org and install it. This will install both Python 3 and pip3. ## virtualenv Once Python 3 is installed, open a Terminal and type pip3 install virtualenv This will install virtualenv from the Python Package Index. ---------------- Installing prerequisites for PDF build Same as for HTML plus a compatible LaTeX installation with support for PDFLaTeX. Also the following LaTeX packages need to be installed (e.g. from texlive): Building the PDF format manual requires in addition a compatible LaTeX installation with support for PDFLaTeX and several add-on LaTeX packages installed. This includes: - amsmath - anysize - babel - capt-of - cmap Loading @@ -105,24 +68,13 @@ to be installed (e.g. from texlive): - tabulary - upquote - wrapfig ---------------- Installing prerequisites for epub build ## ePUB Same as for HTML. This uses the same tools and configuration files as the HTML tree. The ePUB format conversion currently does not support processing mathematical expressions via MathJAX, so there will be limitations on some pages. For the time being until this is resolved, building and using the PDF format file is recommended instead. For converting the generated ePUB file to a mobi format file (for e-book readers like Kindle, that cannot read ePUB), you also need to have the 'ebook-convert' tool from the "calibre" software installed. http://calibre-ebook.com/ You first create the ePUB file with 'make epub' and then do: ebook-convert LAMMPS.epub LAMMPS.mobi Building the EPUB format requires LaTeX installation with the same packages as for the PDF format plus the 'dvipng' command to convert the embedded math into images. The MOBI format is generated from the EPUB format file by using the tool 'ebook-convert' from the 'calibre' e-book management software (https://calibre-ebook.com). ---------------- More details this can be found in the manual itself. The online version is at: https://lammps.sandia.gov/doc/Manual_build.html
