lijiext
/
lammps
mirror of https://github.com/lammps/lammps.git
1
0
Fork 1
Code Issues Packages Projects Releases Wiki Activity

add doxygen integration with conventional and cmake doc build

This commit is contained in:
Axel Kohlmeyer 2020-08-24 17:56:17 -04:00
parent dc241abb85
commit 3f685c346f
No known key found for this signature in database
GPG Key ID: D9B44E93BF0C375A
17 changed files with 959 additions and 157 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

56
cmake/Modules/Documentation.cmake
View File

@ -15,6 +15,7 @@ if(BUILD_DOC)
endif()
set(VIRTUALENV ${Python3_EXECUTABLE} -m virtualenv -p ${Python3_EXECUTABLE})
endif()
find_package(Doxygen 1.8.10 REQUIRED)
file(GLOB DOC_SOURCES ${LAMMPS_DOC_DIR}/src/[^.]*.rst)
@ -51,31 +52,56 @@ if(BUILD_DOC)
"${CMAKE_CURRENT_BINARY_DIR}/html/_static/polyfill.js")
endif()
# set up doxygen and add targets to run it
file(MAKE_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/doxygen)
set(DOXYGEN_XML_DIR ${CMAKE_CURRENT_BINARY_DIR}/doxygen/xml)
add_custom_command(
OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/doxygen/lammps-logo.png
DEPENDS ${LAMMPS_DOC_DIR}/doxygen/lammps-logo.png
COMMAND ${CMAKE_COMMAND} -E copy ${LAMMPS_DOC_DIR}/doxygen/lammps-logo.png ${CMAKE_BINARY_DIR}/doxygen/lammps-logo.png
)
configure_file(${LAMMPS_DOC_DIR}/doxygen/Doxyfile.in ${CMAKE_CURRENT_BINARY_DIR}/doxygen/Doxyfile)
get_target_property(LAMMPS_SOURCES lammps SOURCES)
# need to update timestamps on pg_*.rst files after running doxygen to have sphinx re-read them
file(GLOB PG_SOURCES ${LAMMPS_DOC_DIR}/src/pg_*.rst)
add_custom_command(
OUTPUT ${DOXYGEN_XML_DIR}/index.xml
DEPENDS ${DOC_SOURCES} ${LAMMPS_SOURCES}
COMMAND Doxygen::doxygen ${CMAKE_CURRENT_BINARY_DIR}/doxygen/Doxyfile WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/doxygen
COMMAND ${CMAKE_COMMAND} -E touch ${DOXYGEN_XML_DIR}/run.stamp
)
# note, this may run in parallel with other tasks, so we must not use multiple processes here
file(COPY ${LAMMPS_DOC_DIR}/utils/sphinx-config DESTINATION ${CMAKE_CURRENT_BINARY_DIR}/utils)
file(COPY ${LAMMPS_DOC_DIR}/src DESTINATION ${CMAKE_CURRENT_BINARY_DIR})
configure_file(${CMAKE_CURRENT_BINARY_DIR}/utils/sphinx-config/conf.py.in ${CMAKE_CURRENT_BINARY_DIR}/utils/sphinx-config/conf.py)
if(EXISTS ${DOXYGEN_XML_DIR}/run.stamp)
set(SPHINX_EXTRA_OPTS "-E")
else()
set(SPHINX_EXTRA_OPTS "")
endif()
add_custom_command(
OUTPUT html
DEPENDS ${DOC_SOURCES} docenv requirements.txt
COMMAND ${DOCENV_BINARY_DIR}/sphinx-build -b html -c ${LAMMPS_DOC_DIR}/utils/sphinx-config -d ${CMAKE_BINARY_DIR}/doctrees ${LAMMPS_DOC_DIR}/src html
DEPENDS ${DOC_SOURCES} docenv requirements.txt ${DOXYGEN_XML_DIR}/index.xml ${CMAKE_CURRENT_BINARY_DIR}/utils/sphinx-config/conf.py
COMMAND ${DOCENV_BINARY_DIR}/sphinx-build ${SPHINX_EXTRA_OPTS} -b html -c ${CMAKE_BINARY_DIR}/utils/sphinx-config -d ${CMAKE_BINARY_DIR}/doctrees ${LAMMPS_DOC_DIR}/src html
COMMAND ${CMAKE_COMMAND} -E create_symlink Manual.html ${CMAKE_CURRENT_BINARY_DIR}/html/index.html
COMMAND ${CMAKE_COMMAND} -E remove -f ${DOXYGEN_XML_DIR}/run.stamp
)
# copy selected image files to html output tree
file(MAKE_DIRECTORY ${CMAKE_BINARY_DIR}/html/JPG)
set(HTML_EXTRA_IMAGES balance_nonuniform.jpg balance_rcb.jpg
balance_uniform.jpg bow_tutorial_01.png bow_tutorial_02.png
bow_tutorial_03.png bow_tutorial_04.png bow_tutorial_05.png
dump1.jpg dump2.jpg examples_mdpd.gif gran_funnel.png gran_mixer.png
hop1.jpg hop2.jpg saed_ewald_intersect.jpg saed_mesh.jpg
screenshot_atomeye.jpg screenshot_gl.jpg screenshot_pymol.jpg
screenshot_vmd.jpg sinusoid.jpg xrd_mesh.jpg)
file(MAKE_DIRECTORY ${CMAKE_BINARY_DIR}/html/_images/wsl_tutorial)
file(GLOB HTML_EXTRA_IMAGES RELATIVE ${LAMMPS_DOC_DIR}/src/img/
${LAMMPS_DOC_DIR}/src/img/[^.]*.jpg
${LAMMPS_DOC_DIR}/src/img/[^.]*.gif
${LAMMPS_DOC_DIR}/src/img/[^.]*.png
${LAMMPS_DOC_DIR}/src/img/wsl_tutorial/[^.]*.png)
set(HTML_IMAGE_TARGETS "")
foreach(_IMG ${HTML_EXTRA_IMAGES})
string(PREPEND _IMG JPG/)
list(APPEND HTML_IMAGE_TARGETS "${CMAKE_CURRENT_BINARY_DIR}/html/${_IMG}")
list(APPEND HTML_IMAGE_TARGETS "${CMAKE_CURRENT_BINARY_DIR}/html/_images/${_IMG}")
add_custom_command(
OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/html/${_IMG}
DEPENDS ${LAMMPS_DOC_DIR}/src/${_IMG} ${CMAKE_CURRENT_BINARY_DIR}/html/JPG
COMMAND ${CMAKE_COMMAND} -E copy ${LAMMPS_DOC_DIR}/src/${_IMG} ${CMAKE_BINARY_DIR}/html/${_IMG}
OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/html/_images/${_IMG}
DEPENDS ${LAMMPS_DOC_DIR}/src/img/${_IMG} ${CMAKE_CURRENT_BINARY_DIR}/html/_images
COMMAND ${CMAKE_COMMAND} -E copy ${LAMMPS_DOC_DIR}/src/img/${_IMG} ${CMAKE_BINARY_DIR}/html/_images/${_IMG}
)
endforeach()

5
doc/.gitignore vendored
View File

@ -1,6 +1,7 @@
/old
/html
/html-offline
/epub
/latex
/mathjax
/spelling
@ -10,3 +11,7 @@
/Developer.pdf
/doctrees
/docenv
/doxygen-warn.log
/utils/sphinx-config/conf.py
/doxygen/Doxyfile
*.el

102
doc/Makefile
View File

@ -1,21 +1,29 @@
# Makefile for LAMMPS documentation
SHELL = /bin/bash
BUILDDIR = ${CURDIR}
RSTDIR = $(BUILDDIR)/src
VENV = $(BUILDDIR)/docenv
MATHJAX = $(BUILDDIR)/mathjax
TXT2RST = $(VENV)/bin/txt2rst
ANCHORCHECK = $(VENV)/bin/rst_anchor_check
SHELL = /bin/bash
BUILDDIR = ${CURDIR}
RSTDIR = $(BUILDDIR)/src
VENV = $(BUILDDIR)/docenv
MATHJAX = $(BUILDDIR)/mathjax
POLYFILL = $(BUILDDIR)/mathjax/polyfill.js
TXT2RST = $(VENV)/bin/txt2rst
ANCHORCHECK = $(VENV)/bin/rst_anchor_check
SPHINXCONFIG = $(BUILDDIR)/utils/sphinx-config
PYTHON = $(shell which python3)
PYTHON = $(shell which python3)
DOXYGEN = $(shell which doxygen)
VIRTUALENV = virtualenv
HAS_PYTHON3 = NO
HAS_VIRTUALENV = NO
HAS_DOXYGEN = NO
HAS_PDFLATEX = NO
ifeq ($(shell which python3 >/dev/null 2>&1; echo $$?), 0)
HAS_PYTHON3 = YES
HAS_PYTHON3 = YES
endif
ifeq ($(shell which doxygen >/dev/null 2>&1; echo $$?), 0)
HAS_DOXYGEN = YES
endif
ifeq ($(shell which virtualenv-3 >/dev/null 2>&1; echo $$?), 0)
@ -33,9 +41,13 @@ HAS_PDFLATEX = YES
endif
SPHINXEXTRA = -j $(shell $(PYTHON) -c 'import multiprocessing;print(multiprocessing.cpu_count())')
SPHINXEXTRA = -j $(shell $(PYTHON) -c 'import multiprocessing;print(multiprocessing.cpu_count())') $(shell test -f $(BUILDDIR)/doxygen/xml/run.stamp && printf -- "-E")
.PHONY: help clean-all clean clean-spelling epub mobi rst html pdf spelling anchor_check style_check
# grab list of sources from doxygen config file.
# we only want to use explicitly listed files.
DOXYFILES = $(shell sed -n -e 's/\#.*$$//' -e '/^ *INPUT \+=/,/^[A-Z_]\+ \+=/p' doxygen/Doxyfile.in | sed -e 's/@LAMMPS_SOURCE_DIR@/..\/src/g' -e 's/\\//g' -e 's/ \+/ /' -e 's/[A-Z_]\+ \+= *\(YES\|NO\|\)//')
.PHONY: help clean-all clean clean-spelling epub mobi rst html pdf spelling anchor_check style_check xmlgen
# ------------------------------------------
@ -57,23 +69,32 @@ help:
# ------------------------------------------
clean-all: clean
rm -rf $(BUILDDIR)/docenv $(BUILDDIR)/doctrees $(BUILDDIR)/mathjax Manual.pdf Developer.pdf
rm -rf $(BUILDDIR)/docenv $(MATHJAX) $(BUILDDIR)/LAMMPS.mobi $(BUILDDIR)/LAMMPS.epub $(BUILDDIR)/Manual.pdf $(BUILDDIR)/Developer.pdf
clean: clean-spelling
rm -rf html epub latex
rm -rf $(BUILDDIR)/html $(BUILDDIR)/epub $(BUILDDIR)/latex $(BUILDDIR)/doctrees $(BUILDDIR)/doxygen/xml $(BUILDDIR)/doxygen-warn.log $(BUILDDIR)/doxygen/Doxyfile $(SPHINXCONFIG)/conf.py
clean-spelling:
rm -rf spelling
rm -rf $(BUILDDIR)/spelling
html: $(ANCHORCHECK) $(MATHJAX)
$(SPHINXCONFIG)/conf.py: $(SPHINXCONFIG)/conf.py.in
sed -e 's,@DOXYGEN_XML_DIR@,$(BUILDDIR)/doxygen/xml,g' \
-e 's,@LAMMPS_SOURCE_DIR@,$(BUILDDIR)/../src,g' \
-e 's,@LAMMPS_PYTHON_DIR@,$(BUILDDIR)/../python,g' \
-e 's,@LAMMPS_DOC_DIR@,$(BUILDDIR),g' $< > $@
html: xmlgen $(SPHINXCONFIG)/conf.py $(ANCHORCHECK) $(MATHJAX) $(POLYFILL)
@$(MAKE) $(MFLAGS) -C graphviz all
@(\
. $(VENV)/bin/activate ;\
sphinx-build $(SPHINXEXTRA) -b html -c utils/sphinx-config -d $(BUILDDIR)/doctrees $(RSTDIR) html ;\
. $(VENV)/bin/activate ; env PYTHONWARNINGS= \
sphinx-build $(SPHINXEXTRA) -b html -c $(SPHINXCONFIG) -d $(BUILDDIR)/doctrees $(RSTDIR) html ;\
ln -sf Manual.html html/index.html;\
rm -f $(BUILDDIR)/doxygen/xml/run.stamp;\
echo "############################################" ;\
rst_anchor_check src/*.rst ;\
python utils/check-packages.py -s ../src -d src ;\
python $(BUILDDIR)/utils/check-packages.py -s ../src -d src ;\
env LC_ALL=C grep -n '[^ -~]' $(RSTDIR)/*.rst ;\
python utils/check-styles.py -s ../src -d src ;\
python $(BUILDDIR)/utils/check-styles.py -s ../src -d src ;\
echo "############################################" ;\
deactivate ;\
)
@ -87,25 +108,29 @@ html: $(ANCHORCHECK) $(MATHJAX)
@rm -rf html/PDF/.[sg]*
@mkdir -p html/_static/mathjax
@cp -r $(MATHJAX)/es5 html/_static/mathjax/
@cp $(POLYFILL) html/_static/
@echo "Build finished. The HTML pages are in doc/html."
spelling: $(VENV) utils/sphinx-config/false_positives.txt
spelling: xmlgen $(VENV) $(SPHINXCONFIG)/false_positives.txt
@(\
. $(VENV)/bin/activate ;\
cp utils/sphinx-config/false_positives.txt $(RSTDIR)/ ; env PYTHONWARNINGS= \
sphinx-build -b spelling -c utils/sphinx-config -d $(BUILDDIR)/doctrees $(RSTDIR) spelling ;\
. $(VENV)/bin/activate ; env PYTHONWARNINGS= \
cp $(SPHINXCONFIG)/false_positives.txt $(RSTDIR)/ ; env PYTHONWARNINGS= \
sphinx-build -b spelling -c $(SPHINXCONFIG) -d $(BUILDDIR)/doctrees $(RSTDIR) spelling ;\
rm -f $(BUILDDIR)/doxygen/xml/run.stamp;\
deactivate ;\
)
@echo "Spell check finished."
epub: $(VENV)
epub: xmlgen $(VENV) $(SPHINXCONFIG)/conf.py $(ANCHORCHECK)
@$(MAKE) $(MFLAGS) -C graphviz all
@mkdir -p epub/JPG
@rm -f LAMMPS.epub
@cp src/JPG/lammps-logo.png epub/
@cp src/JPG/*.* epub/JPG
@(\
. $(VENV)/bin/activate ;\
sphinx-build $(SPHINXEXTRA) -b epub -c utils/sphinx-config -d $(BUILDDIR)/doctrees $(RSTDIR) epub ;\
sphinx-build $(SPHINXEXTRA) -b epub -c $(SPHINXCONFIG) -d $(BUILDDIR)/doctrees $(RSTDIR) epub ;\
rm -f $(BUILDDIR)/doxygen/xml/run.stamp;\
deactivate ;\
)
@mv epub/LAMMPS.epub .
@ -117,7 +142,8 @@ mobi: epub
@ebook-convert LAMMPS.epub LAMMPS.mobi
@echo "Conversion finished. The MOBI manual file is created."
pdf: $(ANCHORCHECK)
pdf: xmlgen $(VENV) $(SPHINXCONFIG)/conf.py $(ANCHORCHECK)
@$(MAKE) $(MFLAGS) -C graphviz all
@if [ "$(HAS_PDFLATEX)" == "NO" ] ; then echo "PDFLaTeX was not found! Please check README.md for further instructions" 1>&2; exit 1; fi
@(\
cd src/Developer; \
@ -127,8 +153,9 @@ pdf: $(ANCHORCHECK)
cd ../../; \
)
@(\
. $(VENV)/bin/activate ;\
sphinx-build $(SPHINXEXTRA) -b latex -c utils/sphinx-config -d $(BUILDDIR)/doctrees $(RSTDIR) latex ;\
. $(VENV)/bin/activate ; env PYTHONWARNINGS= \
sphinx-build $(SPHINXEXTRA) -b latex -c $(SPHINXCONFIG) -d $(BUILDDIR)/doctrees $(RSTDIR) latex ;\
rm -f $(BUILDDIR)/doxygen/xml/run.stamp;\
echo "############################################" ;\
rst_anchor_check src/*.rst ;\
python utils/check-packages.py -s ../src -d src ;\
@ -185,21 +212,32 @@ package_check : $(VENV)
deactivate ;\
)
xmlgen : doxygen/xml/index.xml
doxygen/Doxyfile: doxygen/Doxyfile.in
sed -e 's/@LAMMPS_SOURCE_DIR@/..\/..\/src/g' $< > $@
doxygen/xml/index.xml : $(VENV) doxygen/Doxyfile $(DOXYFILES)
@(cd doxygen; $(DOXYGEN) Doxyfile && touch xml/run.stamp)
# ------------------------------------------
$(VENV):
@if [ "$(HAS_PYTHON3)" == "NO" ] ; then echo "Python3 was not found! Please check README.md for further instructions" 1>&2; exit 1; fi
@if [ "$(HAS_VIRTUALENV)" == "NO" ] ; then echo "virtualenv was not found! Please check README.md for further instructions" 1>&2; exit 1; fi
@if [ "$(HAS_PYTHON3)" == "NO" ] ; then echo "python3 was not found! Please see README for further instructions" 1>&2; exit 1; fi
@if [ "$(HAS_DOXYGEN)" == "NO" ] ; then echo "doxygen was not found! Please see README for further instructions" 1>&2; exit 1; fi
@if [ "$(HAS_VIRTUALENV)" == "NO" ] ; then echo "virtualenv was not found! Please see README for further instructions" 1>&2; exit 1; fi
@( \
$(VIRTUALENV) -p $(PYTHON) $(VENV); \
. $(VENV)/bin/activate; \
pip install --upgrade pip; \
pip install --use-feature=2020-resolver -r requirements.txt; \
pip install --use-feature=2020-resolver -r $(BUILDDIR)/utils/requirements.txt; \
deactivate;\
)
$(MATHJAX):
@git clone --depth 1 https://github.com/mathjax/MathJax.git mathjax
@git clone --depth 1 https://github.com/mathjax/MathJax.git $@
$(POLYFILL): $(MATHJAX)
@curl -s -o $@ "https://polyfill.io/v3/polyfill.min.js?features=es6"
$(TXT2RST) $(ANCHORCHECK): $(VENV)
@( \

148
doc/README
View File

@ -1,97 +1,60 @@
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:
Depending on how you obtained LAMMPS and whether you have built
the manual yourself, this directory has a varying number of
sub-directories and files. Here is a list with descriptions:
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
README this 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 PDF version of entire manual
Developer.pdf PDF with info about how LAMMPS is structured
LAMMPS.epub Manual in ePUB format
LAMMPS.mobi Manual in MOBI (Kindle) format
lammps.1 man page for the lammps command
msi2lmp.1 man page for the msi2lmp command
mathjax code and fonts for rendering math in html
doctree temporary data
docenv python virtual environment for generating the manual
doxygen Doxygen configuration and output
.gitignore list of files and folders to be ignored by git
doxygen-warn.log logfile with warnings from running doxygen
If you downloaded LAMMPS as a tarball from the web site, all these
directories and files should be included.
and:
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:
github-development-workflow.md notes on the LAMMPS development workflow
include-file-conventions.md notes on LAMMPS' include file conventions
documentation_conventions.md notes on writing documentation for LAMMPS
If you downloaded a LAMMPS tarball from lammps.sandia.gov, then the html
folder and the PDF manual should be included. If you downloaded LAMMPS
from GitHub then you either need to download them or build them.
(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).
Manual_www.pdf/Developer_www.pdf files. These files will always
represent the latest published patch/development version of LAMMPS.
(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.
(b) You can build the HTML and PDF files yourself, by typing "make html"
or by "make pdf", respectively. This requires various tools and files.
Some of them have to be installed (more on that below). For the rest the
build process will attempt to download and install into a python virtual
environment and local folders.
----------------
The generation of all documentation is managed by the Makefile in this
dir.
Installing prerequisites for the documentation build
Options:
To run the HTML documention build toolchain, python 3.x, doxygen, git,
and virtualenv have to be installed. Also internet access is initially
required to download external files and tools.
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):
Building the PDF format manual requires in addition a compatible LaTeX
installation with support for PDFLaTeX and several add-on LaTeX packages
installed. This includes:
- amsmath
- anysize
- babel
- capt-of
- cmap
@ -105,24 +68,13 @@ to be installed (e.g. from texlive):
- tabulary
- upquote
- wrapfig
Building the EPUB format requires LaTeX installation with the same packages
as for the PDF format plus the 'dvipng' command to convert the embedded math
into images. The MOBI format is generated from the EPUB format file by using
the tool 'ebook-convert' from the 'calibre' e-book management software
(https://calibre-ebook.com).
----------------
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
More details this can be found in the manual itself. The online
version is at: https://lammps.sandia.gov/doc/Manual_build.html

93
doc/documentation_conventions.md Normal file
View File

@ -0,0 +1,93 @@
# Outline of LAMMPS documentation file conventions
This purpose of this document is to provide a point of reference
for LAMMPS developers and contributors as to what conventions
should be used to structure and format files in the LAMMPS manual.
Last change: 2020-04-23
## File format and tools
In fall 2019, the LAMMPS documentation file format has changed from
a home grown minimal markup designed to generate HTML format files
from a mostly plain text format to using the reStructuredText file
format. For a transition period all files in the old .txt format
were transparently converted to .rst and then processed. The txt2rst
tool is still included in the distribution to obtain an initial .rst
file for integration into the manual. Since the transition to
reStructured text as source format, many of the artifacts or the
translation have been removed though and parts of the documentation
refactored and expanded to take advantage of the capabilities
reStructuredText and associated tools. The conversion from the
source to the final formats (HTML, PDF, and optionally e-book
reader formats ePUB and MOBI) is mostly automated and controlled
by a Makefile in the `doc` folder. This makefile assumes that the
processing is done on a Unix-like machine and Python 3.5 or later
and a matching virtualenv module are available. Additional Python
packages (like the Sphinx tool and several extensions) are
transparently installed into a virtual environment over the
internet using the `pip` package manager. Further requirements
and details are discussed in the manual.
## Work in progress
The refactoring and improving of the documentation is an ongoing
process, so statements in this document may not always be fully
up-to-date. If in doubt, contact the LAMMPS developers.
## General structure
The layout and formatting of added files should follow the example
of the existing files. Since those are directly derived from their
former .txt format versions and the manual has been maintained in
that format for many years, there is a large degree of consistency
already, so comparision with similar files should give you a good
idea what kind of information and sections are needed.
## Formatting conventions
Filenames, folders, paths, (shell) commands, definitions, makefile
settings and similar should be formatted as "literals" with
double backward quotes bracketing the item: \`\`path/to/some/file\`\`
Keywords and options are formatted in italics: \*option\*
Mathematical expressions, equations, symbols are typeset using
either a `.. math:`` block or the `:math:` role.
Groups of shell commands or LAMMPS input script or C/C++ source
code should be typeset into a `.. code-block::` section. A syntax
highlighting extension for LAMMPS input scripts is provided, so
`LAMMPS` can be used to indicate the language in the code block
in addition to `bash`, `c`, or `python`. When no syntax style
is indicated, no syntax highlighting is performed.
As an alternative, e.g. to typeset the syntax of file formats
a `.. parsed-literal::` block can be used, which allows some
formatting directives, which means that related characters need
to be escaped with a preceding backslash: `\*`.
Special remarks can be highlighted with a `.. note::` block and
strong warnings can be put into a `.. warning::` block.
## Required steps when adding a custom style to LAMMPS
When adding a new style (e.g. pair style or a compute or a fix)
or a new command, it is **required** to include the corresponding
documentation. Those are often new files that need to be added.
In order to be included in the documentation, those new files
need to be reference in a `.. toctree::` block. Most of those
use patterns with wildcards, so the addition will be automatic.
However, those additions also need to be added to some lists of
styles or commands. The `make style\_check` command will perform
a test and report any missing entries and list the affected files.
Any references defined with `.. \_refname:` have to be unique
across all documentation files and this can be checked for with
`make anchor\_check`. Finally, a spell-check should be done,
which is triggered via `make spelling`. Any offenses need to
be corrected and false positives should be added to the file
`utils/sphinx-config/false\_positives.txt`.
## Required additional steps when adding a new package to LAMMPS
TODO

1
doc/doxygen/.gitignore vendored Normal file
View File

@ -0,0 +1 @@
/xml

522
doc/doxygen/Doxyfile.in Normal file
View File

@ -0,0 +1,522 @@
# Doxyfile 1.8.15 -*- makefile -*-
DOXYFILE_ENCODING = UTF-8
PROJECT_NAME = "LAMMPS Programmer's Guide"
PROJECT_NUMBER = "24 August 2020"
PROJECT_BRIEF = "Documentation of the LAMMPS library interface and Python wrapper"
PROJECT_LOGO = lammps-logo.png
CREATE_SUBDIRS = NO
ALLOW_UNICODE_NAMES = NO
OUTPUT_LANGUAGE = English
OUTPUT_TEXT_DIRECTION = LTR
BRIEF_MEMBER_DESC = YES
REPEAT_BRIEF = YES
ALWAYS_DETAILED_SEC = NO
INLINE_INHERITED_MEMB = NO
FULL_PATH_NAMES = NO
INHERIT_DOCS = YES
TAB_SIZE = 2
# When enabled doxygen tries to link words that correspond to documented
# classes, or namespaces to their corresponding documentation. Such a link can
# be prevented in individual cases by putting a % sign in front of the word or
# globally by setting AUTOLINK_SUPPORT to NO.
# The default value is: YES.
AUTOLINK_SUPPORT = YES
# If you use STL classes (i.e. std::string, std::vector, etc.) but do not want
# to include (a tag file for) the STL sources as input, then you should set this
# tag to YES in order to let doxygen match functions declarations and
# definitions whose arguments contain STL classes (e.g. func(std::string);
# versus func(std::string) {}). This also make the inheritance and collaboration
# diagrams that involve STL classes more complete and accurate.
# The default value is: NO.
BUILTIN_STL_SUPPORT = YES
IDL_PROPERTY_SUPPORT = NO
# The size of the symbol lookup cache can be set using LOOKUP_CACHE_SIZE. This
# cache is used to resolve symbols given their name and scope. Since this can be
# an expensive process and often the same symbol appears multiple times in the
# code, doxygen keeps a cache of pre-resolved symbols. If the cache is too small
# doxygen will become slower. If the cache is too large, memory is wasted. The
# cache size is given by this formula: 2^(16+LOOKUP_CACHE_SIZE). The valid range
# is 0..9, the default is 0, corresponding to a cache size of 2^16=65536
# symbols. At the end of a run doxygen will report the cache usage and suggest
# the optimal cache size from a speed point of view.
# Minimum value: 0, maximum value: 9, default value: 0.
LOOKUP_CACHE_SIZE = 2
#---------------------------------------------------------------------------
# Build related configuration options
#---------------------------------------------------------------------------
# If the EXTRACT_ALL tag is set to YES, doxygen will assume all entities in
# documentation are documented, even if no documentation was available. Private
# class members and static file members will be hidden unless the
# EXTRACT_PRIVATE respectively EXTRACT_STATIC tags are set to YES.
# Note: This will also disable the warnings about undocumented members that are
# normally produced when WARNINGS is set to YES.
# The default value is: NO.
EXTRACT_ALL = NO
# If the EXTRACT_PRIVATE tag is set to YES, all private members of a class will
# be included in the documentation.
# The default value is: NO.
EXTRACT_PRIVATE = YES
# If the EXTRACT_PACKAGE tag is set to YES, all members with package or internal
# scope will be included in the documentation.
# The default value is: NO.
EXTRACT_PACKAGE = YES
# If the EXTRACT_STATIC tag is set to YES, all static members of a file will be
# included in the documentation.
# The default value is: NO.
EXTRACT_STATIC = YES
# If the EXTRACT_LOCAL_CLASSES tag is set to YES, classes (and structs) defined
# locally in source files will be included in the documentation. If set to NO,
# only classes defined in header files are included. Does not have any effect
# for Java sources.
# The default value is: YES.
EXTRACT_LOCAL_CLASSES = YES
# If this flag is set to YES, the members of anonymous namespaces will be
# extracted and appear in the documentation as a namespace called
# 'anonymous_namespace{file}', where file will be replaced with the base name of
# the file that contains the anonymous namespace. By default anonymous namespace
# are hidden.
# The default value is: NO.
EXTRACT_ANON_NSPACES = YES
# If the HIDE_UNDOC_MEMBERS tag is set to YES, doxygen will hide all
# undocumented members inside documented classes or files. If set to NO these
# members will be included in the various overviews, but no documentation
# section is generated. This option has no effect if EXTRACT_ALL is enabled.
# The default value is: NO.
HIDE_UNDOC_MEMBERS = YES
# If the HIDE_UNDOC_CLASSES tag is set to YES, doxygen will hide all
# undocumented classes that are normally visible in the class hierarchy. If set
# to NO, these classes will be included in the various overviews. This option
# has no effect if EXTRACT_ALL is enabled.
# The default value is: NO.
HIDE_UNDOC_CLASSES = YES
# If the HIDE_FRIEND_COMPOUNDS tag is set to YES, doxygen will hide all friend
# (class|struct|union) declarations. If set to NO, these declarations will be
# included in the documentation.
# The default value is: NO.
HIDE_FRIEND_COMPOUNDS = NO
# If the HIDE_IN_BODY_DOCS tag is set to YES, doxygen will hide any
# documentation blocks found inside the body of a function. If set to NO, these
# blocks will be appended to the function's detailed documentation block.
# The default value is: NO.
HIDE_IN_BODY_DOCS = NO
# The INTERNAL_DOCS tag determines if documentation that is typed after a
# \internal command is included. If the tag is set to NO then the documentation
# will be excluded. Set it to YES to include the internal documentation.
# The default value is: NO.
INTERNAL_DOCS = NO
# If the CASE_SENSE_NAMES tag is set to NO then doxygen will only generate file
# names in lower-case letters. If set to YES, upper-case letters are also
# allowed. This is useful if you have classes or files whose names only differ
# in case and if your file system supports case sensitive file names. Windows
# and Mac users are advised to set this option to NO.
# The default value is: system dependent.
CASE_SENSE_NAMES = YES
# If the HIDE_SCOPE_NAMES tag is set to NO then doxygen will show members with
# their full class and namespace scopes in the documentation. If set to YES, the
# scope will be hidden.
# The default value is: NO.
HIDE_SCOPE_NAMES = YES
# If the HIDE_COMPOUND_REFERENCE tag is set to NO (default) then doxygen will
# append additional text to a page's title, such as Class Reference. If set to
# YES the compound reference will be hidden.
# The default value is: NO.
HIDE_COMPOUND_REFERENCE= NO
# If the SHOW_INCLUDE_FILES tag is set to YES then doxygen will put a list of
# the files that are included by a file in the documentation of that file.
# The default value is: YES.
SHOW_INCLUDE_FILES = NO
# If the SHOW_GROUPED_MEMB_INC tag is set to YES then Doxygen will add for each
# grouped member an include statement to the documentation, telling the reader
# which file to include in order to use the member.
# The default value is: NO.
SHOW_GROUPED_MEMB_INC = NO
# If the FORCE_LOCAL_INCLUDES tag is set to YES then doxygen will list include
# files with double quotes in the documentation rather than with sharp brackets.
# The default value is: NO.
FORCE_LOCAL_INCLUDES = NO
# If the INLINE_INFO tag is set to YES then a tag [inline] is inserted in the
# documentation for inline members.
# The default value is: YES.
INLINE_INFO = YES
# If the SORT_MEMBER_DOCS tag is set to YES then doxygen will sort the
# (detailed) documentation of file and class members alphabetically by member
# name. If set to NO, the members will appear in declaration order.
# The default value is: YES.
SORT_MEMBER_DOCS = NO
# If the SORT_BRIEF_DOCS tag is set to YES then doxygen will sort the brief
# descriptions of file, namespace and class members alphabetically by member
# name. If set to NO, the members will appear in declaration order. Note that
# this will also influence the order of the classes in the class list.
# The default value is: NO.
SORT_BRIEF_DOCS = NO
# If the SORT_MEMBERS_CTORS_1ST tag is set to YES then doxygen will sort the
# (brief and detailed) documentation of class members so that constructors and
# destructors are listed first. If set to NO the constructors will appear in the
# respective orders defined by SORT_BRIEF_DOCS and SORT_MEMBER_DOCS.
# Note: If SORT_BRIEF_DOCS is set to NO this option is ignored for sorting brief
# member documentation.
# Note: If SORT_MEMBER_DOCS is set to NO this option is ignored for sorting
# detailed member documentation.
# The default value is: NO.
SORT_MEMBERS_CTORS_1ST = NO
# If the SORT_GROUP_NAMES tag is set to YES then doxygen will sort the hierarchy
# of group names into alphabetical order. If set to NO the group names will
# appear in their defined order.
# The default value is: NO.
SORT_GROUP_NAMES = NO
# If the SORT_BY_SCOPE_NAME tag is set to YES, the class list will be sorted by
# fully-qualified names, including namespaces. If set to NO, the class list will
# be sorted only by class name, not including the namespace part.
# Note: This option is not very useful if HIDE_SCOPE_NAMES is set to YES.
# Note: This option applies only to the class list, not to the alphabetical
# list.
# The default value is: NO.
SORT_BY_SCOPE_NAME = NO
# If the STRICT_PROTO_MATCHING option is enabled and doxygen fails to do proper
# type resolution of all parameters of a function it will reject a match between
# the prototype and the implementation of a member function even if there is
# only one candidate or it is obvious which candidate to choose by doing a
# simple string match. By disabling STRICT_PROTO_MATCHING doxygen will still
# accept a match between prototype and implementation in such cases.
# The default value is: NO.
STRICT_PROTO_MATCHING = NO
# The GENERATE_TODOLIST tag can be used to enable (YES) or disable (NO) the todo
# list. This list is created by putting \todo commands in the documentation.
# The default value is: YES.
GENERATE_TODOLIST = YES
# The GENERATE_TESTLIST tag can be used to enable (YES) or disable (NO) the test
# list. This list is created by putting \test commands in the documentation.
# The default value is: YES.
GENERATE_TESTLIST = YES
# The GENERATE_BUGLIST tag can be used to enable (YES) or disable (NO) the bug
# list. This list is created by putting \bug commands in the documentation.
# The default value is: YES.
GENERATE_BUGLIST = YES
# The GENERATE_DEPRECATEDLIST tag can be used to enable (YES) or disable (NO)
# the deprecated list. This list is created by putting \deprecated commands in
# the documentation.
# The default value is: YES.
GENERATE_DEPRECATEDLIST= YES
# The ENABLED_SECTIONS tag can be used to enable conditional documentation
# sections, marked by \if <section_label> ... \endif and \cond <section_label>
# ... \endcond blocks.
ENABLED_SECTIONS =
# The MAX_INITIALIZER_LINES tag determines the maximum number of lines that the
# initial value of a variable or macro / define can have for it to appear in the
# documentation. If the initializer consists of more lines than specified here
# it will be hidden. Use a value of 0 to hide initializers completely. The
# appearance of the value of individual variables and macros / defines can be
# controlled using \showinitializer or \hideinitializer command in the
# documentation regardless of this setting.
# Minimum value: 0, maximum value: 10000, default value: 30.
MAX_INITIALIZER_LINES = 30
# Set the SHOW_USED_FILES tag to NO to disable the list of files generated at
# the bottom of the documentation of classes and structs. If set to YES, the
# list will mention the files that were used to generate the documentation.
# The default value is: YES.
SHOW_USED_FILES = YES
# Set the SHOW_FILES tag to NO to disable the generation of the Files page. This
# will remove the Files entry from the Quick Index and from the Folder Tree View
# (if specified).
# The default value is: YES.
SHOW_FILES = NO
# Set the SHOW_NAMESPACES tag to NO to disable the generation of the Namespaces
# page. This will remove the Namespaces entry from the Quick Index and from the
# Folder Tree View (if specified).
# The default value is: YES.
SHOW_NAMESPACES = YES
# The FILE_VERSION_FILTER tag can be used to specify a program or script that
# doxygen should invoke to get the current version for each file (typically from
# the version control system). Doxygen will invoke the program by executing (via
# popen()) the command command input-file, where command is the value of the
# FILE_VERSION_FILTER tag, and input-file is the name of an input file provided
# by doxygen. Whatever the program writes to standard output is used as the file
# version. For an example see the documentation.
FILE_VERSION_FILTER =
# The LAYOUT_FILE tag can be used to specify a layout file which will be parsed
# by doxygen. The layout file controls the global structure of the generated
# output files in an output format independent way. To create the layout file
# that represents doxygen's defaults, run doxygen with the -l option. You can
# optionally specify a file name after the option, if omitted DoxygenLayout.xml
# will be used as the name of the layout file.
#
# Note that if you run doxygen from a directory containing a file called
# DoxygenLayout.xml, doxygen will parse it automatically even if the LAYOUT_FILE
# tag is left empty.
LAYOUT_FILE =
# The CITE_BIB_FILES tag can be used to specify one or more bib files containing
# the reference definitions. This must be a list of .bib files. The .bib
# extension is automatically appended if omitted. This requires the bibtex tool
# to be installed. See also https://en.wikipedia.org/wiki/BibTeX for more info.
# For LaTeX the style of the bibliography can be controlled using
# LATEX_BIB_STYLE. To use this feature you need bibtex and perl available in the
# search path. See also \cite for info how to create references.
CITE_BIB_FILES =
#---------------------------------------------------------------------------
# Configuration options related to warning and progress messages
#---------------------------------------------------------------------------
# The QUIET tag can be used to turn on/off the messages that are generated to
# standard output by doxygen. If QUIET is set to YES this implies that the
# messages are off.
# The default value is: NO.
QUIET = NO
# The WARNINGS tag can be used to turn on/off the warning messages that are
# generated to standard error (stderr) by doxygen. If WARNINGS is set to YES
# this implies that the warnings are on.
#
# Tip: Turn warnings on while writing the documentation.
# The default value is: YES.
WARNINGS = YES
# If the WARN_IF_UNDOCUMENTED tag is set to YES then doxygen will generate
# warnings for undocumented members. If EXTRACT_ALL is set to YES then this flag
# will automatically be disabled.
# The default value is: YES.
WARN_IF_UNDOCUMENTED = YES
# If the WARN_IF_DOC_ERROR tag is set to YES, doxygen will generate warnings for
# potential errors in the documentation, such as not documenting some parameters
# in a documented function, or documenting parameters that don't exist or using
# markup commands wrongly.
# The default value is: YES.
WARN_IF_DOC_ERROR = YES
# This WARN_NO_PARAMDOC option can be enabled to get warnings for functions that
# are documented, but have no documentation for their parameters or return
# value. If set to NO, doxygen will only warn about wrong or incomplete
# parameter documentation, but not about the absence of documentation. If
# EXTRACT_ALL is set to YES then this flag will automatically be disabled.
# The default value is: NO.
WARN_NO_PARAMDOC = YES
# If the WARN_AS_ERROR tag is set to YES then doxygen will immediately stop when
# a warning is encountered.
# The default value is: NO.
WARN_AS_ERROR = NO
# The WARN_FORMAT tag determines the format of the warning messages that doxygen
# can produce. The string should contain the $file, $line, and $text tags, which
# will be replaced by the file and line number from which the warning originated
# and the warning text. Optionally the format may contain $version, which will
# be replaced by the version of the file (if it could be obtained via
# FILE_VERSION_FILTER)
# The default value is: $file:$line: $text.
WARN_FORMAT = "$file:$line: $text"
# The WARN_LOGFILE tag can be used to specify a file to which warning and error
# messages should be written. If left blank the output is written to standard
# error (stderr).
WARN_LOGFILE = "../doxygen-warn.log"
#---------------------------------------------------------------------------
# Configuration options related to the input files
#---------------------------------------------------------------------------
# The INPUT tag is used to specify the files and/or directories that contain
# documented source files. You may enter file names like myfile.cpp or
# directories like /usr/src/myproject. Separate the files or directories with
# spaces. See also FILE_PATTERNS and EXTENSION_MAPPING
# Note: If this tag is empty the current directory is searched.
INPUT = @LAMMPS_SOURCE_DIR@/utils.cpp \
@LAMMPS_SOURCE_DIR@/utils.h \
@LAMMPS_SOURCE_DIR@/library.cpp \
@LAMMPS_SOURCE_DIR@/library.h \
@LAMMPS_SOURCE_DIR@/lammps.cpp \
@LAMMPS_SOURCE_DIR@/lammps.h \
@LAMMPS_SOURCE_DIR@/lmptype.h \
@LAMMPS_SOURCE_DIR@/pointers.h \
@LAMMPS_SOURCE_DIR@/atom.cpp \
@LAMMPS_SOURCE_DIR@/atom.h \
@LAMMPS_SOURCE_DIR@/input.cpp \
@LAMMPS_SOURCE_DIR@/input.h \
# The EXCLUDE_SYMLINKS tag can be used to select whether or not files or
# directories that are symbolic links (a Unix file system feature) are excluded
# from the input.
# The default value is: NO.
EXCLUDE_SYMLINKS = YES
#---------------------------------------------------------------------------
# Configuration options related to output
#---------------------------------------------------------------------------
GENERATE_HTML = NO
GENERATE_LATEX = NO
GENERATE_XML = YES
XML_OUTPUT = xml
XML_PROGRAMLISTING = YES
XML_NS_MEMB_FILE_SCOPE = NO
#---------------------------------------------------------------------------
# Configuration options related to the preprocessor
#---------------------------------------------------------------------------
# If the ENABLE_PREPROCESSING tag is set to YES, doxygen will evaluate all
# C-preprocessor directives found in the sources and include files.
# The default value is: YES.
#ENABLE_PREPROCESSING = YES
ENABLE_PREPROCESSING = NO
# If the MACRO_EXPANSION tag is set to YES, doxygen will expand all macro names
# in the source code. If set to NO, only conditional compilation will be
# performed. Macro expansion can be done in a controlled way by setting
# EXPAND_ONLY_PREDEF to YES.
# The default value is: NO.
# This tag requires that the tag ENABLE_PREPROCESSING is set to YES.
MACRO_EXPANSION = NO
# If the EXPAND_ONLY_PREDEF and MACRO_EXPANSION tags are both set to YES then
# the macro expansion is limited to the macros specified with the PREDEFINED and
# EXPAND_AS_DEFINED tags.
# The default value is: NO.
# This tag requires that the tag ENABLE_PREPROCESSING is set to YES.
EXPAND_ONLY_PREDEF = NO
# If the SEARCH_INCLUDES tag is set to YES, the include files in the
# INCLUDE_PATH will be searched if a #include is found.
# The default value is: YES.
# This tag requires that the tag ENABLE_PREPROCESSING is set to YES.
SEARCH_INCLUDES = YES
# The INCLUDE_PATH tag can be used to specify one or more directories that
# contain include files that are not input files but should be processed by the
# preprocessor.
# This tag requires that the tag SEARCH_INCLUDES is set to YES.
INCLUDE_PATH =
# You can use the INCLUDE_FILE_PATTERNS tag to specify one or more wildcard
# patterns (like *.h and *.hpp) to filter out the header-files in the
# directories. If left blank, the patterns specified with FILE_PATTERNS will be
# used.
# This tag requires that the tag ENABLE_PREPROCESSING is set to YES.
INCLUDE_FILE_PATTERNS =
# The PREDEFINED tag can be used to specify one or more macro names that are
# defined before the preprocessor is started (similar to the -D option of e.g.
# gcc). The argument of the tag is a list of macros of the form: name or
# name=definition (no spaces). If the definition and the "=" are omitted, "=1"
# is assumed. To prevent a macro definition from being undefined via #undef or
# recursively expanded use the := operator instead of the = operator.
# This tag requires that the tag ENABLE_PREPROCESSING is set to YES.
PREDEFINED =
# If the MACRO_EXPANSION and EXPAND_ONLY_PREDEF tags are set to YES then this
# tag can be used to specify a list of macro names that should be expanded. The
# macro definition that is found in the sources will be used. Use the PREDEFINED
# tag if you want to use a different macro definition that overrules the
# definition found in the source code.
# This tag requires that the tag ENABLE_PREPROCESSING is set to YES.
EXPAND_AS_DEFINED =
# If the SKIP_FUNCTION_MACROS tag is set to YES then doxygen's preprocessor will
# remove all references to function-like macros that are alone on a line, have
# an all uppercase name, and do not end with a semicolon. Such function macros
# are typically used for boiler-plate code, and will confuse the parser if not
# removed.
# The default value is: YES.
# This tag requires that the tag ENABLE_PREPROCESSING is set to YES.
SKIP_FUNCTION_MACROS = YES

BIN
doc/doxygen/lammps-logo.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 13 KiB

3
doc/graphviz/.gitignore vendored Normal file
View File

@ -0,0 +1,3 @@
/*.png
/*.svg
/*.pdf

30
doc/graphviz/Makefile Normal file
View File

@ -0,0 +1,30 @@
# Makefile for generating images with graphviz
#
SHELL = /bin/bash
BUILDDIR = ${CURDIR}/..
IMGDIR = $(BUILDDIR)/src/JPG
IMGSRC = $(wildcard *.dot)
IMGPNG = $(IMGSRC:%.dot=$(IMGDIR)/%.png)
HAS_DOT = NO
ifeq ($(shell which dot >/dev/null 2>&1; echo $$?), 0)
HAS_DOT = YES
endif
all: $(IMGPNG)
clean:
rm -f $(IMGSVG) $(IMGPDF) $(IMGPNG) *~
ifeq ($(HAS_DOT),YES)
$(IMGDIR)/%.png: %.dot
dot -Tpng -o $@ $<
endif
ifeq ($(HAS_DOT),NO)
$(IMGDIR)/%.png: %.dot
@echo '###################################################'
@echo '# Need to install "graphviz" to regenerate graphs #'
@echo '###################################################'
endif

90
doc/graphviz/lammps-classes.dot Normal file
View File

@ -0,0 +1,90 @@
// LAMMPS Class topology
digraph lammps {
rankdir="LR"
La [shape=circle label="LAMMPS"]
At [shape=box label="Atom" color=blue]
Ci [shape=box label="CiteMe"]
Co [shape=box label="Comm" color=blue]
Do [shape=box label="Domain" color=blue]
Er [shape=box label="Error" color=blue]
Fo [shape=box label="Force" color=blue]
Gr [shape=box label="Group" color=blue]
In [shape=box label="Input" color=blue]
Ko [shape=box label="KokkosLMP"]
Ak [shape=box label="AtomKK" color=blue]
Mk [shape=box label="MemoryKK" color=blue]
Me [shape=box label="Memory" color=blue]
Mo [shape=box label="Modify" color=blue]
Ne [shape=box label="Neighbor" color=blue]
Ou [shape=box label="Output" color=blue]
Py [shape=box label="Python" color=blue]
Up [shape=box label="Update" color=blue]
Un [shape=box label="Universe" color=blue]
Ti [shape=box label="Timer" color=blue]
Rg [label="Region" color=red]
Rb [shape=box label="RegionBlock"]
Rs [shape=box label="RegionSphere"]
Av [label="AtomVec" color=red]
It [label="Integrate" color=red]
Mi [label="Min" color=red]
Pa [label="Pair" color=red]
Bo [label="Bond" color=red]
An [label="Angle" color=red]
Di [label="Dihedral" color=red]
Im [label="Improper" color=red]
Ks [label="Kspace" color=red]
Du [label="Dump" color=red]
Fi [label="Fix" color=red]
Cp [label="Compute" color=red]
Th [label="Thermo"]
Va [label="Variable"]
Ew [shape=box label="Ewald"]
Pp [shape=box label="PPPM"]
Ff [label="FFT3d"]
Re [label="Remap"]
Gc [label="GridComm"]
Cb [shape=box label="CommBrick"]
Ct [shape=box label="CommTiled"]
Aa [shape=box label="AtomVecAtomic"]
Am [shape=box label="AtomVecMolecular"]
Lj [shape=box label="PairLJCut"]
Lo [shape=box label="PairLJCutOMP"]
Lg [shape=box label="PairLJCutGPU"]
Te [shape=box label="PairTersoff"]
Bh [shape=box label="BondHarmonic"]
Bf [shape=box label="BondFENE"]
Fa [shape=box label="FixAveTime"]
Fn [shape=box label="FixNVE"]
Fh [shape=box label="FixNH"]
Fp [shape=box label="FixNPT"]
Ft [shape=box label="FixNVT"]
Da [shape=box label="DumpAtom"]
Dc [shape=box label="DumpCustom"]
Dg [shape=box label="DumpCFG"]
Ve [shape=box label="Verlet"]
Rr [shape=box label="Respa"]
Po [shape=box label="PPPMOmp"]
La -> {At Ci Co Do Er Fo Gr In Ko Ak Mk Me Mo Ne Ou Py Ti Up Un} [penwidth=2]
Do -> {Rg} [penwidth=2]
Co -> {Cb Ct} [style=dashed penwidth=2]
Rg -> {Rb Rs} [style=dashed penwidth=2]
In -> Va [penwidth=2]
Mo -> {Fi Cp} [penwidth=2]
Fo -> {Pa Bo An Di Im Ks} [penwidth=2]
Ks -> {Ew Pp} [style=dashed penwidth=2]
Pp -> {Ff Re Gc} [penwidth=2]
Pp -> {Po} [style=dashed penwidth=2]
Up -> {It Mi} [penwidth=2]
It -> {Ve Rr} [style=dashed penwidth=2]
Ou -> {Du Th} [penwidth=2]
Du -> {Da Dc} [style=dashed penwidth=2]
Dc -> {Dg} [style=dashed penwidth=2]
At -> Av [penwidth=2]
Av -> {Aa Am} [style=dashed penwidth=2]
Pa -> {Lj Te} [style=dashed penwidth=2]
Lj -> {Lo Lg} [style=dashed penwidth=2]
Bo -> {Bh Bf} [style=dashed penwidth=2]
Fi -> {Fa Fn Fh} [style=dashed penwidth=2]
Fh -> {Fp Ft} [style=dashed penwidth=2]
}

4
doc/requirements.txt
View File

@ -1,4 +0,0 @@
Sphinx
sphinxcontrib-spelling
breathe
Pygments

BIN
doc/src/JPG/lammps-classes.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 245 KiB

4
doc/utils/requirements.txt
View File

@ -1 +1,5 @@
Sphinx
sphinxcontrib-spelling
sphinx-fortran
breathe
Pygments

7
doc/utils/sphinx-config/_static/css/lammps.css
View File

@ -7,3 +7,10 @@
display: block;
margin-bottom: 0.809em;
}
.lammps_release {
text-align: center;
font-size: 11px;
display: block;
margin-bottom: 0.405em;
}

11
doc/utils/sphinx-config/_themes/lammps_theme/layout.html
View File

@ -103,6 +103,12 @@
{%- endif %}
{%- endblock %}
{%- block extrahead %} {% endblock %}
{# Keep modernizr in head - http://modernizr.com/docs/#installing #}
<script src="{{ pathto('_static/js/modernizr.min.js', 1) }}"></script>
{# for improved browser compatibility #}
<script src="{{ pathto('_static/polyfill.js', 1) }}"></script>
</head>
<body class="wy-body-for-nav">
@ -135,9 +141,8 @@
{%- set nav_version = current_version %}
{% endif %}
{% if nav_version %}
<div class="version">
{{ nav_version }}
</div>
<div class="lammps_version">Version: <b>{{ nav_version }}</b></div>
<div class="lammps_release">git info: {{ release }}</div>
{% endif %}
{% endif %}

40
doc/utils/sphinx-config/conf.py → doc/utils/sphinx-config/conf.py.in
View File

@ -27,7 +27,7 @@ except:
# add these directories to sys.path here. If the directory is relative to the
# documentation root, use os.path.abspath to make it absolute, like shown here.
#sys.path.insert(0, os.path.abspath('.'))
sys.path.append(os.path.join(os.path.dirname(__file__), '../../src/_ext'))
sys.path.append(os.path.join('@LAMMPS_DOC_DIR@', 'src', '_ext'))
# -- General configuration ------------------------------------------------
@ -41,7 +41,9 @@ extensions = [
'sphinx.ext.mathjax',
'sphinx.ext.imgmath',
'sphinx.ext.autodoc',
'sphinxfortran.fortran_domain',
'table_from_list',
'breathe',
]
# 2017-12-07: commented out, since this package is broken with Sphinx 16.x
# yet we can no longer use Sphinx 15.x, since that breaks with
@ -72,12 +74,24 @@ copyright = '2003-2020 Sandia Corporation'
def get_lammps_version():
import os
script_dir = os.path.dirname(os.path.realpath(__file__))
with open(os.path.join(script_dir, '../../../src/version.h'), 'r') as f:
with open(os.path.join('@LAMMPS_SOURCE_DIR@', 'version.h'), 'r') as f:
line = f.readline()
start_pos = line.find('"')+1
end_pos = line.find('"', start_pos)
return line[start_pos:end_pos]
def get_git_info():
import subprocess,time
git_n_date = ''
try:
gitinfo = subprocess.run(['git','describe'],stdout=subprocess.PIPE,stderr=subprocess.PIPE)
if gitinfo.returncode == 0:
git_n_date = gitinfo.stdout.decode().replace('_',' ')
except:
pass
return git_n_date
# The version info for the project you're documenting, acts as replacement for
# |version| and |release|, also used in various other places throughout the
# built documents.
@ -85,7 +99,7 @@ def get_lammps_version():
# The short X.Y version.
version = get_lammps_version()
# The full version, including alpha/beta/rc tags.
release = ''
release = get_git_info()
# The language for content autogenerated by Sphinx. Refer to documentation
# for a list of supported languages.
@ -342,13 +356,29 @@ if spelling_spec and has_enchant:
spelling_lang='en_US'
spelling_word_list_filename='false_positives.txt'
sys.path.append(os.path.join(os.path.dirname(__file__), '.'))
conf_script_dir = os.path.dirname(os.path.realpath(__file__))
sys.path.append(os.path.join(conf_script_dir, '.'))
import LAMMPSLexer
from sphinx.highlighting import lexers
lexers['LAMMPS'] = LAMMPSLexer.LAMMPSLexer(startinline=True)
sys.path.append(os.path.join(os.path.dirname(__file__), '../../../python'))
sys.path.append('@LAMMPS_PYTHON_DIR@')
# avoid syntax highlighting in blocks that don't specify language
highlight_language = 'none'
# autodoc configuration
autodoc_member_order = 'bysource'
#autoclass_content = 'both'
# breathe configuration
breathe_projects = { 'progguide' : '@DOXYGEN_XML_DIR@' }
breathe_default_project = 'progguide'
breathe_show_define_initializer = True
breathe_domain_by_extension = { 'h' : 'cpp',
'cpp' : 'cpp',
'c' : 'c',
}