3.9. Build the LAMMPS documentation — LAMMPS documentation

\(\renewcommand{\AA}{\text{Å}}\)

# 3.9. Build the LAMMPS documentation

Depending on how you obtained LAMMPS and whether you have built the manual yourself, this directory has a number of subdirectories and files. Here is a list with descriptions:

    README           # brief info about the documentation
    src              # content files for LAMMPS documentation
    html             # HTML version of the LAMMPS manual (see html/Manual.html)
    utils            # tools and settings for building the documentation
    lammps.1         # man page for the lammps command
    msi2lmp.1        # man page for the msi2lmp command
    Manual.pdf       # large PDF version of entire manual
    LAMMPS.epub      # Manual in ePUB e-book format
    LAMMPS.mobi      # Manual in MOBI e-book format
    docenv           # virtualenv folder for processing the manual sources
    doctrees         # temporary data from processing 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
    github-development-workflow.md   # notes on the LAMMPS development workflow

If you downloaded LAMMPS as a tarball from the LAMMPS website, the html folder and the PDF files should be included.

If you downloaded LAMMPS from the public git repository, then the HTML and PDF files are not included. You can build the HTML or PDF files yourself, by typing `make html` or `make pdf` in the `doc` folder. This requires various tools and files. Some of them have to be installed (see below). For the rest the build process will attempt to download and install them into a python virtual environment and local folders.

A current version of the manual (latest feature release, that is the state of the release branch) is is available online at: https://docs.lammps.org/. A version of the manual corresponding to the ongoing development (that is the state of the develop branch) is available online at: https://docs.lammps.org/latest/ A version of the manual corresponding to the latest stable LAMMPS release (that is the state of the stable branch) is available online at: https://docs.lammps.org/stable/

## 3.9.1. Build using GNU make

The LAMMPS manual is written in reStructuredText format which can be translated to different output format using the Sphinx document generator tool. It also incorporates programmer documentation extracted from the LAMMPS C++ sources through the Doxygen program. Currently the translation to HTML, PDF (via LaTeX), ePUB (for many e-book readers) and MOBI (for Amazon Kindle readers) are supported. For that to work a Python interpreter version 3.8 or later, the `doxygen` tools and internet access to download additional files and tools are required. This download is usually only required once or after the documentation folder is returned to a pristine state with `make clean-all`. You can also upgrade those packages to their latest available versions with `make upgrade`.

For the documentation build a python virtual environment is set up in the folder `doc/docenv` and various python packages are installed into that virtual environment via the `pip` tool. For rendering embedded LaTeX code also the MathJax JavaScript engine needs to be downloaded. If you need to pass additional options to the pip commands to work (e.g. to use a web proxy or to point to additional SSL certificates) you can set them via the `PIP_OPTIONS` environment variable or uncomment and edit the `PIP_OPTIONS` setting at beginning of the makefile.

The actual translation is then done via `make` commands in the doc folder. The following `make` commands are available:

    make html          # generate HTML in html dir using Sphinx
    make pdf           # generate PDF  as Manual.pdf using Sphinx and PDFLaTeX
    make epub          # generate LAMMPS.epub in ePUB format using Sphinx
    make mobi          # generate LAMMPS.mobi in MOBI format using ebook-convert

    make fasthtml      # generate approximate HTML in fasthtml dir using pandoc

    make clean         # remove intermediate RST files created by HTML build
    make clean-all     # remove entire build folder and any cached data
    make upgrade       # upgrade the python packages in the virtual environment

    make anchor_check  # check for duplicate anchor labels
    make style_check   # check for complete and consistent style lists
    make package_check # check for complete and consistent package lists
    make link_check    # check for broken or outdated URLs
    make spelling      # spell-check the manual

## 3.9.2. Build using CMake

It is also possible to create the HTML version (and only the HTML version) of the manual within the CMake build directory. The reason for this option is to include the installation of the HTML manual pages into the “install” step when installing LAMMPS after the CMake build via `cmake --build . --target install`. The documentation build is included in the default build target, but can also be requested independently with `cmake --build . --target doc`. If you need to pass additional options to the pip commands to work (e.g. to use a web proxy or to point to additional SSL certificates) you can set them via the `PIP_OPTIONS` environment variable.

    -D BUILD_DOC=value       # yes or no (default)

## 3.9.3. Prerequisites for HTML

To run the HTML documentation build toolchain, Python 3.8 or later, git, doxygen, and virtualenv have to be installed locally. Here are instructions for common setups:

    sudo apt-get install git doxygen

    sudo dnf install git doxygen

Python 3

If Python 3 is not available on your macOS system, you can download the latest Python 3 macOS package from https://www.python.org and install it. This will install both Python 3 and pip3.

## 3.9.4. Prerequisites for PDF

In addition to the tools needed for building the HTML format manual, a working LaTeX installation with support for PDFLaTeX and a selection of LaTeX styles/packages are required. Apart from LaTeX packages that are usually installed by default, the following packages are required:

amsmath | anysize | babel | capt-of | cmap | dvipng | ellipse | fncychap | fontawesome | framed | geometry
gyre | hyperref | hypcap | needspace | pict2e | times | tabulary | titlesec | upquote | wrapfig | xindy

To run the PDFLaTeX translation the `latexmk` script needs to be installed as well.

## 3.9.5. Prerequisites for ePUB and MOBI

In addition to the tools needed for building the HTML format manual, a working LaTeX installation with a few add-on LaTeX packages as well as the `dvipng` tool are required to convert embedded math expressions transparently into embedded images.

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. https://calibre-ebook.com/ Typing `make mobi` will first create the ePUB file and then convert it. On the Kindle readers in particular, you also have support for PDF files, so you could download and view the PDF version as an alternative.

## 3.9.6. Instructions for Developers

When adding new styles or options to the LAMMPS code, corresponding documentation is required and either existing files in the `src` folder need to be updated or new files added. These files are written in reStructuredText markup for translation with the Sphinx tool.

### Testing your contribution

Before contributing any documentation, please check that both the HTML and the PDF format documentation can translate without errors and that there are no spelling issues. This is done with `make html`, `make pdf`, and `make spelling`, respectively.

### Fast and approximate translation to HTML

Translating the full manual to HTML or PDF can take a long time. Thus there is a fast and approximate way to translate the reStructuredText to HTML as a quick-n-dirty way of checking your manual page.

This translation uses Pandoc instead of Sphinx and thus all special Sphinx features (cross-references, advanced tables, embedding of Python docstrings or doxygen documentation, and so on) will not render correctly. Most embedded math should render correctly. This is a very fast way to check the syntax and layout of a documentation file translated to HTML while writing or updating it.

To translate all manual pages, you can type `make fasthtml` at the command line. The translated HTML files are then in the `fasthtml` folder. All subsequent `make fasthtml` commands will only translate `.rst` files that have been changed. The `make fasthtml` command can be parallelized with make using the -j flag. You can also directly translate only individual pages: e.g. to translate only the `doc/src/pair_lj.rst` page type `make fasthtml/pair_lj.html`

After writing the documentation is completed, you will still need to verify with `make html` and `make pdf` that it translates correctly in both formats.

### Tests for consistency, completeness, and other known issues

Please also check the output to the console for any warnings or problems. There will be multiple tests run automatically:

- A test for correctness of all anchor labels and their references

- A test that all LAMMPS packages (= folders with sources in `lammps/src`) are documented and listed. A typical warning shows the name of the folder with the suspected new package code and the documentation files where they need to be listed:

      Found 88 packages
      Package NEWPACKAGE missing in Packages_list.rst
      Package NEWPACKAGE missing in Packages_details.rst

- A test that only standard, printable ASCII text characters are used. This runs the command `env LC_ALL=C grep -n '[^ -~]' src/*.rst` and thus prints all offending lines with filename and line number prepended to the screen. Special characters like Greek letters (\(\alpha~~\sigma~~\epsilon\)), super- or subscripts (\(x^2~~\mathrm{U}_{LJ}\)), mathematical expressions (\(\frac{1}{2}\mathrm{N}~~x\to\infty\)), or the Angstrom symbol (\(\AA\)) should be typeset with embedded LaTeX (like this `:math:`\alpha \sigma \epsilon``, `:math:`x^2 \mathrm{E}_{LJ}``, `:math:`\frac{1}{2}\mathrm{N} x\to\infty``, or `:math:`\AA``).

- Embedded LaTeX is rendered in HTML output with MathJax and in PDF output by passing the embedded text to LaTeX. Some care has to be taken, though, since there are limitations which macros and features can be used in either mode, so it is recommended to always check whether any new or changed documentation does translate and render correctly with either output.

- A test whether all styles are documented and listed in their respective overview pages. A typical output with warnings looks like this:

      Parsed style names w/o suffixes from C++ tree in ../src:
         Angle styles:      21    Atom styles:       24
         Body styles:        3    Bond styles:       17
         Command styles:    41    Compute styles:   143
         Dihedral styles:   16    Dump styles:       26
         Fix styles:       223    Improper styles:   13
         Integrate styles:   4    Kspace styles:     15
         Minimize styles:    9    Pair styles:      234
         Reader styles:      4    Region styles:      8
      Compute style entry newcomp is missing or incomplete in Commands_compute.rst
      Compute style entry newcomp is missing or incomplete in compute.rst
      Fix style entry newfix is missing or incomplete in Commands_fix.rst
      Fix style entry newfix is missing or incomplete in fix.rst
      Pair style entry new is missing or incomplete in Commands_pair.rst
      Pair style entry new is missing or incomplete in pair_style.rst
      Found 6 issue(s) with style lists

In addition, there is the option to run a spellcheck on the entire manual with `make spelling`. This requires a library called enchant. To avoid printing out false positives (e.g. keywords, names, abbreviations) those can be added to the file `lammps/doc/utils/sphinx-config/false_positives.txt`.