forked from lijiext/lammps
123 lines
4.0 KiB
Plaintext
123 lines
4.0 KiB
Plaintext
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:
|
|
|
|
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
|
|
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:
|
|
|
|
(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.
|
|
|
|
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
|
|
|
|
----------------
|
|
|
|
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
|
|
|
|
## Python 3
|
|
|
|
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):
|
|
- amsmath
|
|
- babel
|
|
- cmap
|
|
- fncychap
|
|
- geometry
|
|
- hyperref
|
|
- hypcap
|
|
- times
|
|
----------------
|
|
|
|
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
|
|
|