mirror of https://github.com/lammps/lammps.git
add doxygen integration with conventional and cmake doc build
This commit is contained in:
parent
dc241abb85
commit
3f685c346f
|
@ -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()
|
||||
|
||||
|
|
|
@ -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
|
||||
|
|
84
doc/Makefile
84
doc/Makefile
|
@ -5,19 +5,27 @@ 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)
|
||||
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
|
||||
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)
|
||||
VIRTUALENV = virtualenv-3
|
||||
HAS_VIRTUALENV = YES
|
||||
|
@ -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)
|
||||
@( \
|
||||
|
|
140
doc/README
140
doc/README
|
@ -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:
|
||||
|
||||
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 large PDF version of entire manual
|
||||
Developer.pdf small PDF with info about how LAMMPS is structured
|
||||
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
|
||||
|
|
|
@ -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
|
|
@ -0,0 +1 @@
|
|||
/xml
|
|
@ -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
|
||||
|
Binary file not shown.
After Width: | Height: | Size: 13 KiB |
|
@ -0,0 +1,3 @@
|
|||
/*.png
|
||||
/*.svg
|
||||
/*.pdf
|
|
@ -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
|
||||
|
|
@ -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]
|
||||
}
|
||||
|
|
@ -1,4 +0,0 @@
|
|||
Sphinx
|
||||
sphinxcontrib-spelling
|
||||
breathe
|
||||
Pygments
|
Binary file not shown.
After Width: | Height: | Size: 245 KiB |
|
@ -1 +1,5 @@
|
|||
Sphinx
|
||||
sphinxcontrib-spelling
|
||||
sphinx-fortran
|
||||
breathe
|
||||
Pygments
|
||||
|
|
|
@ -7,3 +7,10 @@
|
|||
display: block;
|
||||
margin-bottom: 0.809em;
|
||||
}
|
||||
|
||||
.lammps_release {
|
||||
text-align: center;
|
||||
font-size: 11px;
|
||||
display: block;
|
||||
margin-bottom: 0.405em;
|
||||
}
|
||||
|
|
|
@ -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 %}
|
||||
|
||||
|
|
|
@ -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',
|
||||
}
|
Loading…
Reference in New Issue