doc page sync with SVN

# Makefile for LAMMPS documentation

SHELL 	      = /bin/bash

SHA1          = $(shell echo $USER-$PWD | python utils/sha1sum.py)

BUILDDIR      = /tmp/lammps-docs-$(SHA1)

RSTDIR        = $(BUILDDIR)/rst

SOURCES=$(wildcard src/*.txt)

OBJECTS=$(SOURCES:src/%.txt=$(RSTDIR)/%.rst)

.PHONY: help clean-all clean html pdf venv

.PHONY: help clean-all clean html pdf old venv

# ------------------------------------------

help:

	@echo "Please use \`make <target>' where <target> is one of"

	@echo "  html       to make HTML version of documentation using Sphinx"

	@echo "  pdf        to make Manual.pdf"

	@echo "  txt2html   to build txt2html tool"

	@echo "  clean      to remove all generated RST files"

	@echo "  clean-all  to reset the entire build environment"

	@echo "  html       create HTML doc pages in html dir"

	@echo "  pdf        create Manual.pdf and Developer.pdf in this dir"

	@echo "  old        create old-style HTML doc pages in old dir"

	@echo "  fetch      fetch HTML and PDF files from LAMMPS web site"

	@echo "  clean      remove all intermediate RST files"

	@echo "  clean-all  reset the entire build environment"

	@echo "  txt2html   build txt2html tool"

# ------------------------------------------

clean-all:

	rm -rf $(BUILDDIR)/* utils/txt2html/txt2html.exe

clean:

	rm -rf $(RSTDIR)

txt2html: utils/txt2html/txt2html.exe

html: $(OBJECTS)

	@(\

		. $(VENV)/bin/activate ;\

		deactivate ;\

	)

	-rm html/searchindex.js

	-rm -rf html/_sources

	@rm -rf html/_sources

	@rm -rf html/PDF

	@rm -rf html/USER

	@cp -r src/PDF html/PDF

	@cp -r src/USER html/USER

	@rm -rf html/PDF/.[sg]*

	@rm -rf html/USER/.[sg]*

	@rm -rf html/USER/*/.[sg]*

	@rm -rf html/USER/*/*.[sg]*

	@echo "Build finished. The HTML pages are in doc/html."

pdf: utils/txt2html/txt2html.exe

	@(\

		cd src; \

		../utils/txt2html/txt2html.exe -b *.txt; \

		htmldoc --batch ../lammps.book;          \

		htmldoc --batch lammps.book;          \

		for s in `echo *.txt | sed -e 's,\.txt,\.html,g'` ; \

			do grep -q $$s ../lammps.book || \

			echo doc file $$s missing in lammps.book; done; \

			do grep -q $$s lammps.book || \

			echo doc file $$s missing in src/lammps.book; done; \

		rm *.html; \

		cd Developer; \

		pdflatex developer; \

		pdflatex developer; \

		mv developer.pdf ../../Developer.pdf; \

	)

old: utils/txt2html/txt2html.exe

	@rm -rf old

	@mkdir old; mkdir old/Eqs; mkdir old/JPG; mkdir old/PDF

	@cd src; ../utils/txt2html/txt2html.exe -b *.txt; \

	  mv *.html ../old; \

	  cp Eqs/*.jpg ../old/Eqs; \

	  cp JPG/* ../old/JPG; \

	  cp PDF/* ../old/PDF;

fetch:

	@rm -rf html_www Manual_www.pdf Developer_www.pdf

	@curl -s -o Manual_www.pdf http://lammps.sandia.gov/doc/Manual.pdf

	@curl -s -o Developer_www.pdf http://lammps.sandia.gov/doc/Developer.pdf

	@curl -s -o lammps-doc.tar.gz http://lammps.sandia.gov/tars/lammps-doc.tar.gz

	@tar xzf lammps-doc.tar.gz

	@rm -f lammps-doc.tar.gz

txt2html: utils/txt2html/txt2html.exe

# ------------------------------------------

utils/txt2html/txt2html.exe: utils/txt2html/txt2html.cpp

	g++ -O -Wall -o $@ $<

Generation of LAMMPS Documentation

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 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 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.

# Generation of LAMMPS Documentation

The generation of all the documentation is managed by the Makefile inside the

`doc/` folder.

## Usage:

```bash

make html         # generate HTML using Sphinx

make pdf          # generate PDF using htmldoc

make clean        # remove generated RST files

make clean-all    # remove entire build folder and any cached data

```

## Installing prerequisites

To run the documention build toolchain, Python 3 and virtualenv have

to be installed. Here are instructions for common setups:

### Ubuntu

```bash

sudo apt-get install python-virtualenv

```

### Fedora (up to version 21), Red Hat Enterprise Linux or CentOS (up to version 7.x)

```bash

sudo yum install python3-virtualenv

```

### Fedora (since version 22)

```bash

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.