Loading cmake/Modules/Documentation.cmake +41 −15 Original line number Diff line number Diff line Loading @@ -15,6 +15,7 @@ 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) Loading Loading @@ -51,31 +52,56 @@ if(BUILD_DOC) "${CMAKE_CURRENT_BINARY_DIR}/html/_static/polyfill.js") endif() # set up doxygen and add targets to run it file(MAKE_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/doxygen) set(DOXYGEN_XML_DIR ${CMAKE_CURRENT_BINARY_DIR}/doxygen/xml) add_custom_command( OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/doxygen/lammps-logo.png DEPENDS ${LAMMPS_DOC_DIR}/doxygen/lammps-logo.png COMMAND ${CMAKE_COMMAND} -E copy ${LAMMPS_DOC_DIR}/doxygen/lammps-logo.png ${CMAKE_BINARY_DIR}/doxygen/lammps-logo.png ) configure_file(${LAMMPS_DOC_DIR}/doxygen/Doxyfile.in ${CMAKE_CURRENT_BINARY_DIR}/doxygen/Doxyfile) get_target_property(LAMMPS_SOURCES lammps SOURCES) # need to update timestamps on pg_*.rst files after running doxygen to have sphinx re-read them file(GLOB PG_SOURCES ${LAMMPS_DOC_DIR}/src/pg_*.rst) add_custom_command( OUTPUT ${DOXYGEN_XML_DIR}/index.xml DEPENDS ${DOC_SOURCES} ${LAMMPS_SOURCES} COMMAND Doxygen::doxygen ${CMAKE_CURRENT_BINARY_DIR}/doxygen/Doxyfile WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/doxygen COMMAND ${CMAKE_COMMAND} -E touch ${DOXYGEN_XML_DIR}/run.stamp ) # note, this may run in parallel with other tasks, so we must not use multiple processes here file(COPY ${LAMMPS_DOC_DIR}/utils/sphinx-config DESTINATION ${CMAKE_CURRENT_BINARY_DIR}/utils) file(COPY ${LAMMPS_DOC_DIR}/src DESTINATION ${CMAKE_CURRENT_BINARY_DIR}) configure_file(${CMAKE_CURRENT_BINARY_DIR}/utils/sphinx-config/conf.py.in ${CMAKE_CURRENT_BINARY_DIR}/utils/sphinx-config/conf.py) if(EXISTS ${DOXYGEN_XML_DIR}/run.stamp) set(SPHINX_EXTRA_OPTS "-E") else() set(SPHINX_EXTRA_OPTS "") endif() 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 DEPENDS ${DOC_SOURCES} docenv requirements.txt ${DOXYGEN_XML_DIR}/index.xml ${CMAKE_CURRENT_BINARY_DIR}/utils/sphinx-config/conf.py COMMAND ${DOCENV_BINARY_DIR}/sphinx-build ${SPHINX_EXTRA_OPTS} -b html -c ${CMAKE_BINARY_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 COMMAND ${CMAKE_COMMAND} -E remove -f ${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) file(MAKE_DIRECTORY ${CMAKE_BINARY_DIR}/html/_images/wsl_tutorial) file(GLOB HTML_EXTRA_IMAGES RELATIVE ${LAMMPS_DOC_DIR}/src/img/ ${LAMMPS_DOC_DIR}/src/img/[^.]*.jpg ${LAMMPS_DOC_DIR}/src/img/[^.]*.gif ${LAMMPS_DOC_DIR}/src/img/[^.]*.png ${LAMMPS_DOC_DIR}/src/img/wsl_tutorial/[^.]*.png) set(HTML_IMAGE_TARGETS "") foreach(_IMG ${HTML_EXTRA_IMAGES}) string(PREPEND _IMG JPG/) list(APPEND HTML_IMAGE_TARGETS "${CMAKE_CURRENT_BINARY_DIR}/html/${_IMG}") list(APPEND HTML_IMAGE_TARGETS "${CMAKE_CURRENT_BINARY_DIR}/html/_images/${_IMG}") 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 ${CMAKE_CURRENT_BINARY_DIR}/html/_images/${_IMG} DEPENDS ${LAMMPS_DOC_DIR}/src/img/${_IMG} ${CMAKE_CURRENT_BINARY_DIR}/html/_images COMMAND ${CMAKE_COMMAND} -E copy ${LAMMPS_DOC_DIR}/src/img/${_IMG} ${CMAKE_BINARY_DIR}/html/_images/${_IMG} ) endforeach() Loading doc/.gitignore +5 −0 Original line number Diff line number Diff line /old /html /html-offline /epub /latex /mathjax /spelling Loading @@ -10,3 +11,7 @@ /Developer.pdf /doctrees /docenv /doxygen-warn.log /utils/sphinx-config/conf.py /doxygen/Doxyfile *.el doc/Makefile +71 −33 Original line number Diff line number Diff line Loading @@ -5,19 +5,27 @@ BUILDDIR = ${CURDIR} RSTDIR = $(BUILDDIR)/src VENV = $(BUILDDIR)/docenv MATHJAX = $(BUILDDIR)/mathjax POLYFILL = $(BUILDDIR)/mathjax/polyfill.js TXT2RST = $(VENV)/bin/txt2rst ANCHORCHECK = $(VENV)/bin/rst_anchor_check SPHINXCONFIG = $(BUILDDIR)/utils/sphinx-config 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 @@ -87,25 +108,29 @@ html: $(ANCHORCHECK) $(MATHJAX) @rm -rf html/PDF/.[sg]* @mkdir -p html/_static/mathjax @cp -r $(MATHJAX)/es5 html/_static/mathjax/ @cp $(POLYFILL) html/_static/ @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 +142,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 +153,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 +212,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 doc/documentation_conventions.md 0 → 100644 +93 −0 Original line number Diff line number Diff line # Outline of LAMMPS documentation file conventions This purpose of this document is to provide a point of reference for LAMMPS developers and contributors as to what conventions should be used to structure and format files in the LAMMPS manual. Last change: 2020-04-23 ## File format and tools In fall 2019, the LAMMPS documentation file format has changed from a home grown minimal markup designed to generate HTML format files from a mostly plain text format to using the reStructuredText file format. For a transition period all files in the old .txt format were transparently converted to .rst and then processed. The txt2rst tool is still included in the distribution to obtain an initial .rst file for integration into the manual. Since the transition to reStructured text as source format, many of the artifacts or the translation have been removed though and parts of the documentation refactored and expanded to take advantage of the capabilities reStructuredText and associated tools. The conversion from the source to the final formats (HTML, PDF, and optionally e-book reader formats ePUB and MOBI) is mostly automated and controlled by a Makefile in the `doc` folder. This makefile assumes that the processing is done on a Unix-like machine and Python 3.5 or later and a matching virtualenv module are available. Additional Python packages (like the Sphinx tool and several extensions) are transparently installed into a virtual environment over the internet using the `pip` package manager. Further requirements and details are discussed in the manual. ## Work in progress The refactoring and improving of the documentation is an ongoing process, so statements in this document may not always be fully up-to-date. If in doubt, contact the LAMMPS developers. ## General structure The layout and formatting of added files should follow the example of the existing files. Since those are directly derived from their former .txt format versions and the manual has been maintained in that format for many years, there is a large degree of consistency already, so comparision with similar files should give you a good idea what kind of information and sections are needed. ## Formatting conventions Filenames, folders, paths, (shell) commands, definitions, makefile settings and similar should be formatted as "literals" with double backward quotes bracketing the item: \`\`path/to/some/file\`\` Keywords and options are formatted in italics: \*option\* Mathematical expressions, equations, symbols are typeset using either a `.. math:`` block or the `:math:` role. Groups of shell commands or LAMMPS input script or C/C++ source code should be typeset into a `.. code-block::` section. A syntax highlighting extension for LAMMPS input scripts is provided, so `LAMMPS` can be used to indicate the language in the code block in addition to `bash`, `c`, or `python`. When no syntax style is indicated, no syntax highlighting is performed. As an alternative, e.g. to typeset the syntax of file formats a `.. parsed-literal::` block can be used, which allows some formatting directives, which means that related characters need to be escaped with a preceding backslash: `\*`. Special remarks can be highlighted with a `.. note::` block and strong warnings can be put into a `.. warning::` block. ## Required steps when adding a custom style to LAMMPS When adding a new style (e.g. pair style or a compute or a fix) or a new command, it is **required** to include the corresponding documentation. Those are often new files that need to be added. In order to be included in the documentation, those new files need to be reference in a `.. toctree::` block. Most of those use patterns with wildcards, so the addition will be automatic. However, those additions also need to be added to some lists of styles or commands. The `make style\_check` command will perform a test and report any missing entries and list the affected files. Any references defined with `.. \_refname:` have to be unique across all documentation files and this can be checked for with `make anchor\_check`. Finally, a spell-check should be done, which is triggered via `make spelling`. Any offenses need to be corrected and false positives should be added to the file `utils/sphinx-config/false\_positives.txt`. ## Required additional steps when adding a new package to LAMMPS TODO Loading
cmake/Modules/Documentation.cmake +41 −15 Original line number Diff line number Diff line Loading @@ -15,6 +15,7 @@ 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) Loading Loading @@ -51,31 +52,56 @@ if(BUILD_DOC) "${CMAKE_CURRENT_BINARY_DIR}/html/_static/polyfill.js") endif() # set up doxygen and add targets to run it file(MAKE_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/doxygen) set(DOXYGEN_XML_DIR ${CMAKE_CURRENT_BINARY_DIR}/doxygen/xml) add_custom_command( OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/doxygen/lammps-logo.png DEPENDS ${LAMMPS_DOC_DIR}/doxygen/lammps-logo.png COMMAND ${CMAKE_COMMAND} -E copy ${LAMMPS_DOC_DIR}/doxygen/lammps-logo.png ${CMAKE_BINARY_DIR}/doxygen/lammps-logo.png ) configure_file(${LAMMPS_DOC_DIR}/doxygen/Doxyfile.in ${CMAKE_CURRENT_BINARY_DIR}/doxygen/Doxyfile) get_target_property(LAMMPS_SOURCES lammps SOURCES) # need to update timestamps on pg_*.rst files after running doxygen to have sphinx re-read them file(GLOB PG_SOURCES ${LAMMPS_DOC_DIR}/src/pg_*.rst) add_custom_command( OUTPUT ${DOXYGEN_XML_DIR}/index.xml DEPENDS ${DOC_SOURCES} ${LAMMPS_SOURCES} COMMAND Doxygen::doxygen ${CMAKE_CURRENT_BINARY_DIR}/doxygen/Doxyfile WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/doxygen COMMAND ${CMAKE_COMMAND} -E touch ${DOXYGEN_XML_DIR}/run.stamp ) # note, this may run in parallel with other tasks, so we must not use multiple processes here file(COPY ${LAMMPS_DOC_DIR}/utils/sphinx-config DESTINATION ${CMAKE_CURRENT_BINARY_DIR}/utils) file(COPY ${LAMMPS_DOC_DIR}/src DESTINATION ${CMAKE_CURRENT_BINARY_DIR}) configure_file(${CMAKE_CURRENT_BINARY_DIR}/utils/sphinx-config/conf.py.in ${CMAKE_CURRENT_BINARY_DIR}/utils/sphinx-config/conf.py) if(EXISTS ${DOXYGEN_XML_DIR}/run.stamp) set(SPHINX_EXTRA_OPTS "-E") else() set(SPHINX_EXTRA_OPTS "") endif() 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 DEPENDS ${DOC_SOURCES} docenv requirements.txt ${DOXYGEN_XML_DIR}/index.xml ${CMAKE_CURRENT_BINARY_DIR}/utils/sphinx-config/conf.py COMMAND ${DOCENV_BINARY_DIR}/sphinx-build ${SPHINX_EXTRA_OPTS} -b html -c ${CMAKE_BINARY_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 COMMAND ${CMAKE_COMMAND} -E remove -f ${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) file(MAKE_DIRECTORY ${CMAKE_BINARY_DIR}/html/_images/wsl_tutorial) file(GLOB HTML_EXTRA_IMAGES RELATIVE ${LAMMPS_DOC_DIR}/src/img/ ${LAMMPS_DOC_DIR}/src/img/[^.]*.jpg ${LAMMPS_DOC_DIR}/src/img/[^.]*.gif ${LAMMPS_DOC_DIR}/src/img/[^.]*.png ${LAMMPS_DOC_DIR}/src/img/wsl_tutorial/[^.]*.png) set(HTML_IMAGE_TARGETS "") foreach(_IMG ${HTML_EXTRA_IMAGES}) string(PREPEND _IMG JPG/) list(APPEND HTML_IMAGE_TARGETS "${CMAKE_CURRENT_BINARY_DIR}/html/${_IMG}") list(APPEND HTML_IMAGE_TARGETS "${CMAKE_CURRENT_BINARY_DIR}/html/_images/${_IMG}") 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 ${CMAKE_CURRENT_BINARY_DIR}/html/_images/${_IMG} DEPENDS ${LAMMPS_DOC_DIR}/src/img/${_IMG} ${CMAKE_CURRENT_BINARY_DIR}/html/_images COMMAND ${CMAKE_COMMAND} -E copy ${LAMMPS_DOC_DIR}/src/img/${_IMG} ${CMAKE_BINARY_DIR}/html/_images/${_IMG} ) endforeach() Loading
doc/.gitignore +5 −0 Original line number Diff line number Diff line /old /html /html-offline /epub /latex /mathjax /spelling Loading @@ -10,3 +11,7 @@ /Developer.pdf /doctrees /docenv /doxygen-warn.log /utils/sphinx-config/conf.py /doxygen/Doxyfile *.el
doc/Makefile +71 −33 Original line number Diff line number Diff line Loading @@ -5,19 +5,27 @@ BUILDDIR = ${CURDIR} RSTDIR = $(BUILDDIR)/src VENV = $(BUILDDIR)/docenv MATHJAX = $(BUILDDIR)/mathjax POLYFILL = $(BUILDDIR)/mathjax/polyfill.js TXT2RST = $(VENV)/bin/txt2rst ANCHORCHECK = $(VENV)/bin/rst_anchor_check SPHINXCONFIG = $(BUILDDIR)/utils/sphinx-config 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 @@ -87,25 +108,29 @@ html: $(ANCHORCHECK) $(MATHJAX) @rm -rf html/PDF/.[sg]* @mkdir -p html/_static/mathjax @cp -r $(MATHJAX)/es5 html/_static/mathjax/ @cp $(POLYFILL) html/_static/ @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 +142,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 +153,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 +212,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
doc/documentation_conventions.md 0 → 100644 +93 −0 Original line number Diff line number Diff line # Outline of LAMMPS documentation file conventions This purpose of this document is to provide a point of reference for LAMMPS developers and contributors as to what conventions should be used to structure and format files in the LAMMPS manual. Last change: 2020-04-23 ## File format and tools In fall 2019, the LAMMPS documentation file format has changed from a home grown minimal markup designed to generate HTML format files from a mostly plain text format to using the reStructuredText file format. For a transition period all files in the old .txt format were transparently converted to .rst and then processed. The txt2rst tool is still included in the distribution to obtain an initial .rst file for integration into the manual. Since the transition to reStructured text as source format, many of the artifacts or the translation have been removed though and parts of the documentation refactored and expanded to take advantage of the capabilities reStructuredText and associated tools. The conversion from the source to the final formats (HTML, PDF, and optionally e-book reader formats ePUB and MOBI) is mostly automated and controlled by a Makefile in the `doc` folder. This makefile assumes that the processing is done on a Unix-like machine and Python 3.5 or later and a matching virtualenv module are available. Additional Python packages (like the Sphinx tool and several extensions) are transparently installed into a virtual environment over the internet using the `pip` package manager. Further requirements and details are discussed in the manual. ## Work in progress The refactoring and improving of the documentation is an ongoing process, so statements in this document may not always be fully up-to-date. If in doubt, contact the LAMMPS developers. ## General structure The layout and formatting of added files should follow the example of the existing files. Since those are directly derived from their former .txt format versions and the manual has been maintained in that format for many years, there is a large degree of consistency already, so comparision with similar files should give you a good idea what kind of information and sections are needed. ## Formatting conventions Filenames, folders, paths, (shell) commands, definitions, makefile settings and similar should be formatted as "literals" with double backward quotes bracketing the item: \`\`path/to/some/file\`\` Keywords and options are formatted in italics: \*option\* Mathematical expressions, equations, symbols are typeset using either a `.. math:`` block or the `:math:` role. Groups of shell commands or LAMMPS input script or C/C++ source code should be typeset into a `.. code-block::` section. A syntax highlighting extension for LAMMPS input scripts is provided, so `LAMMPS` can be used to indicate the language in the code block in addition to `bash`, `c`, or `python`. When no syntax style is indicated, no syntax highlighting is performed. As an alternative, e.g. to typeset the syntax of file formats a `.. parsed-literal::` block can be used, which allows some formatting directives, which means that related characters need to be escaped with a preceding backslash: `\*`. Special remarks can be highlighted with a `.. note::` block and strong warnings can be put into a `.. warning::` block. ## Required steps when adding a custom style to LAMMPS When adding a new style (e.g. pair style or a compute or a fix) or a new command, it is **required** to include the corresponding documentation. Those are often new files that need to be added. In order to be included in the documentation, those new files need to be reference in a `.. toctree::` block. Most of those use patterns with wildcards, so the addition will be automatic. However, those additions also need to be added to some lists of styles or commands. The `make style\_check` command will perform a test and report any missing entries and list the affected files. Any references defined with `.. \_refname:` have to be unique across all documentation files and this can be checked for with `make anchor\_check`. Finally, a spell-check should be done, which is triggered via `make spelling`. Any offenses need to be corrected and false positives should be added to the file `utils/sphinx-config/false\_positives.txt`. ## Required additional steps when adding a new package to LAMMPS TODO
