Project 4 - Update and modernize the LAMMPS manual

Overview and Motivation

History

The LAMMPS manual was originally written in a simple, custom markup language that would translate plain text files into minimal HTML with a txt2html converter program which would mostly deal with structural elements like headlines, links, lists, tables and similar.

Any mathematical expressions had to be typeset as individual LaTeX pages, translated to JPEG images, cropped and then included as images. This would only work well for larger equations and not for single letters or inline expressions. For larger texts with many equations even this procedure would be cumbersome and hence those were translated from LaTeX to PDF and are included as PDF files.

The PDF version of the manual would then be created from the HTML pages using the HTMLDOC tool.

Modern times

As the LAMMPS software was growing and also its documentation, the minimal approach to processing the manual was showing its limitations and the result HTML and PDF documents were not always very readable.

It was then decided to switch to using the Sphinx documentation generator software. The documentation is now written in reStructuredText and uses several extensions that allow to import embedded documentation from Python (directly) and C++ code (via Doxygen), automatic syntax highlighting, and use much more sophisticated typesetting and cross-referencing. For example all math equations can now be embedded directly as LaTeX blocks with the .. math:: directive and will be rendered in HTML output via the MathJax JavaScript code while in PDF output, they are included as part of the LaTeX code that is generated by sphinx. Inline math expressions can now also easily be typeset with the :math: role.

Tasks

  • The current LAMMPS manual still has in places “transcribed” math expressions that could be converted to “:math:<LaTeX code>” segments and thus make their respective pages more readable as the correspond better to the equations.

  • Add more .. versionadded:: directives indicating when exactly (recently added) features were included in LAMMPS. That way LAMMPS users with older LAMMPS versions will know more easily that a command is not supported by their LAMMPS version when they read the online version of the manual (representing the latest version).

  • There are several PDF files that were created externally and could be converted into reStructuredText and then included into the manual as HowTo documents instead of external PDF files. This specifically allows to add cross-references to and from the documentation pages of the individual commands.

  • LAMMPS has many bundled examples but it is not always easy to identify which example could be useful to learn how to use a specific command. GitHub issue #2680 proposes to add information about which examples to look at into the documentation. Examples: pair style e2b, pair style

Example

Old:

where F is the embedding energy which is a function of the atomic
electron density rho, phi is a pair potential interaction, and alpha
and beta are the element types of atoms I and J.

New:

where *F* is the embedding energy which is a function of the atomic
electron density :math:`\rho`, :math:`\phi_{\alpha\beta}()` is a pair
potential interaction, and :math:`\alpha` and :math:`\beta` are the element
types of atoms *i* and *j*.