diff --git a/doc/src/Build_manual.txt b/doc/src/Build_manual.txt new file mode 100644 index 0000000000000000000000000000000000000000..3dfc3d08b305e66ee81d635b245f0d42a18fdefb --- /dev/null +++ b/doc/src/Build_manual.txt @@ -0,0 +1,125 @@ +"Previous Section"_Errors.html - "LAMMPS WWW Site"_lws - +"LAMMPS Documentation"_ld - "LAMMPS Commands"_lc - "Next +Section"_Manual.html :c + +:link(lws,http://lammps.sandia.gov) +:link(ld,Manual.html) +:link(lc,Commands_all.html) + +:line + +Building the LAMMPS Manual :h2 + +Depending on how you obtained LAMMPS, the doc 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) +tools tools 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 :pre + +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" followed by "make pdf". Note that the PDF make requires the +HTML files already exist. This requires various tools including +Sphinx, which the build process will attempt to download and install +on your system, if not already available. See more details below. + +(c) You can genererate an older, simpler, less-fancy style of HTML +documentation by typing "make old". This will create an "old" +directory. This can be useful if (b) does not work on your box for +some reason, or you want to quickly view the HTML version of a doc +page you have created or edited yourself within the src directory. +E.g. if you are planning to submit a new feature to LAMMPS. + +:line + +The generation of all documentation is managed by the Makefile in +the doc dir. + +Documentation Build Options: :pre + +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 old # generate old-style HTML pages in old dir via txt2html +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 :pre + +:line + +Installing prerequisites for HTML build :h3 + +To run the HTML documention build toolchain, Python 3 and virtualenv +have to be installed. Here are instructions for common setups: + +Ubuntu :h4 + +sudo apt-get install python-virtualenv :pre + +Fedora (up to version 21) and Red Hat Enterprise Linux or CentOS (up to version 7.x) :h4 + +sudo yum install python3-virtualenv :pre + +Fedora (since version 22) :h4 + +sudo dnf install python3-virtualenv pre + +MacOS X :h4 + +Python 3 :h5 + +Download the latest Python 3 MacOS X package from +"https://www.python.org"_https://www.python.org +and install it. This will install both Python 3 +and pip3. + +virtualenv :h5 + +Once Python 3 is installed, open a Terminal and type + +pip3 install virtualenv :pre + +This will install virtualenv from the Python Package Index. + +:line + +Installing prerequisites for PDF build + +[TBA] + +:line + +Installing prerequisites for epub build :h3 + +ePUB :h4 + +Same as for HTML. This uses the same tools and configuration +files as the HTML tree. + +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/"_http://calibre-ebook.com/ +You first create the ePUB file with 'make epub' and then do: + +ebook-convert LAMMPS.epub LAMMPS.mobi :pre +