14. Building the LAMMPS manual
Depending on how you obtained LAMMPS, the doc directory has up to 6 sub-directories, 2 Nroff files, and optionally 2 PDF files plus 2 e-book format files:
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 docenv # virtualenv for processing the manual sources doctrees # temporary data from processing the manual mathjax # code and fonts for rendering math in html Manual.pdf # large PDF version of entire manual Developer.pdf # small PDF with info about how LAMMPS is structured LAMMPS.epub # Manual in ePUB e-book format LAMMPS.mobi # Manual in MOBI e-book format lammps.1 # man page for the lammps command msi2lmp.1 # man page for the msi2lmp command
If you downloaded LAMMPS as a tarball from the web site, 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. Instead you need to create them, in one of two ways:
You can “fetch” the current HTML and PDF files from the LAMMPS web site. Just type “make fetch”. This should download a html_www directory and Manual_www.pdf/Developer_www.pdf files. Note that if new LAMMPS features have been added more recently than the date of your LAMMPS version, the fetched documentation will include those changes (but your source code will not, unless you update your local repository).
The generation of all documentation is managed by the Makefile in the doc directory.
Documentation Build Options: make html # generate HTML in html dir using Sphinx make pdf # generate 2 PDF files (Manual.pdf,Developer.pdf) # in doc dir via htmldoc and pdflatex make fetch # fetch HTML doc pages and 2 PDF files from web site # as a tarball and unpack into html dir and 2 PDFs make epub # generate LAMMPS.epub in ePUB format using Sphinx make mobi # generate LAMMPS.mobi in MOBI format using ebook-convert make clean # remove intermediate RST files created by HTML build make clean-all # remove entire build folder and any cached data 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 spelling # spell-check the manual
14.1. Installing prerequisites for HTML build
To run the HTML documentation build toolchain, Python 3 and virtualenv have to be installed. Here are instructions for common setups:
sudo apt-get install python-virtualenv
14.1.2. Fedora (up to version 21) and Red Hat Enterprise Linux or CentOS (up to version 7.x)
sudo yum install python3-virtualenv
14.1.3. Fedora (since version 22)
sudo dnf install python3-virtualenv
14.1.4. MacOS X
Download the latest Python 3 MacOS X package from https://www.python.org and install it. This will install both Python 3 and pip3.
Once Python 3 is installed, open a Terminal and type
pip3 install virtualenv
This will install virtualenv from the Python Package Index.
14.2. Installing prerequisites for epub build
Same as for HTML. This uses mostly the same tools and configuration files as the HTML tree. In addition it uses LaTeX 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. http://calibre-ebook.com/ You first create the ePUB file and then convert it with ‘make mobi’ 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.