diff --git a/cmake/Modules/Documentation.cmake b/cmake/Modules/Documentation.cmake index 282253eede..ddd284aa90 100644 --- a/cmake/Modules/Documentation.cmake +++ b/cmake/Modules/Documentation.cmake @@ -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() diff --git a/doc/.gitignore b/doc/.gitignore index 55b25960db..85c75c2934 100644 --- a/doc/.gitignore +++ b/doc/.gitignore @@ -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 diff --git a/doc/Makefile b/doc/Makefile index 293884b17f..1b5fb35b4c 100644 --- a/doc/Makefile +++ b/doc/Makefile @@ -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) @( \ diff --git a/doc/README b/doc/README index cbc0c425dc..f0c74f7771 100644 --- a/doc/README +++ b/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: -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 diff --git a/doc/documentation_conventions.md b/doc/documentation_conventions.md new file mode 100644 index 0000000000..40526d940d --- /dev/null +++ b/doc/documentation_conventions.md @@ -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 diff --git a/doc/doxygen/.gitignore b/doc/doxygen/.gitignore new file mode 100644 index 0000000000..2539ab748e --- /dev/null +++ b/doc/doxygen/.gitignore @@ -0,0 +1 @@ +/xml diff --git a/doc/doxygen/Doxyfile.in b/doc/doxygen/Doxyfile.in new file mode 100644 index 0000000000..78ac614ca3 --- /dev/null +++ b/doc/doxygen/Doxyfile.in @@ -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 ... \endif and \cond +# ... \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 + diff --git a/doc/doxygen/lammps-logo.png b/doc/doxygen/lammps-logo.png new file mode 100644 index 0000000000..787d855a1c Binary files /dev/null and b/doc/doxygen/lammps-logo.png differ diff --git a/doc/graphviz/.gitignore b/doc/graphviz/.gitignore new file mode 100644 index 0000000000..b134fdb6f1 --- /dev/null +++ b/doc/graphviz/.gitignore @@ -0,0 +1,3 @@ +/*.png +/*.svg +/*.pdf diff --git a/doc/graphviz/Makefile b/doc/graphviz/Makefile new file mode 100644 index 0000000000..fb6411379d --- /dev/null +++ b/doc/graphviz/Makefile @@ -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 + diff --git a/doc/graphviz/lammps-classes.dot b/doc/graphviz/lammps-classes.dot new file mode 100644 index 0000000000..408ab36f65 --- /dev/null +++ b/doc/graphviz/lammps-classes.dot @@ -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] +} + diff --git a/doc/requirements.txt b/doc/requirements.txt deleted file mode 100644 index 045559d8c4..0000000000 --- a/doc/requirements.txt +++ /dev/null @@ -1,4 +0,0 @@ -Sphinx -sphinxcontrib-spelling -breathe -Pygments diff --git a/doc/src/JPG/lammps-classes.png b/doc/src/JPG/lammps-classes.png new file mode 100644 index 0000000000..e673299e9d Binary files /dev/null and b/doc/src/JPG/lammps-classes.png differ diff --git a/doc/utils/requirements.txt b/doc/utils/requirements.txt index 2806c16498..b86522baf4 100644 --- a/doc/utils/requirements.txt +++ b/doc/utils/requirements.txt @@ -1 +1,5 @@ Sphinx +sphinxcontrib-spelling +sphinx-fortran +breathe +Pygments diff --git a/doc/utils/sphinx-config/_static/css/lammps.css b/doc/utils/sphinx-config/_static/css/lammps.css index 751bba3900..d2aa8a975d 100644 --- a/doc/utils/sphinx-config/_static/css/lammps.css +++ b/doc/utils/sphinx-config/_static/css/lammps.css @@ -7,3 +7,10 @@ display: block; margin-bottom: 0.809em; } + +.lammps_release { + text-align: center; + font-size: 11px; + display: block; + margin-bottom: 0.405em; +} diff --git a/doc/utils/sphinx-config/_themes/lammps_theme/layout.html b/doc/utils/sphinx-config/_themes/lammps_theme/layout.html index 9344063304..8e0d235d55 100644 --- a/doc/utils/sphinx-config/_themes/lammps_theme/layout.html +++ b/doc/utils/sphinx-config/_themes/lammps_theme/layout.html @@ -103,6 +103,12 @@ {%- endif %} {%- endblock %} {%- block extrahead %} {% endblock %} + + {# Keep modernizr in head - http://modernizr.com/docs/#installing #} + + + {# for improved browser compatibility #} + @@ -135,9 +141,8 @@ {%- set nav_version = current_version %} {% endif %} {% if nav_version %} -
- {{ nav_version }} -
+
Version: {{ nav_version }}
+
git info: {{ release }}
{% endif %} {% endif %} diff --git a/doc/utils/sphinx-config/conf.py b/doc/utils/sphinx-config/conf.py.in similarity index 90% rename from doc/utils/sphinx-config/conf.py rename to doc/utils/sphinx-config/conf.py.in index cc7dc0741f..92ba10a341 100644 --- a/doc/utils/sphinx-config/conf.py +++ b/doc/utils/sphinx-config/conf.py.in @@ -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', + }