Tools for LAMMPS documentation with the "doxygen" documentation platform

are provided.

        New directory: tools/doxygen

        New file:      tools/doxygen/Developer.dox.lammps
        New file:      tools/doxygen/Doxyfile.lammps
        New file:      tools/doxygen/doxygen.sh
        New file:      tools/doxygen/README

The Developer.dox.lammps file contains a slightly revised version of the
Developer.pdf file adopted to the LAMMPS "doxygen" documentation.

The Doxyfile.lammps file is a first proposal for a LAMMPS "doxygen"
documentation flavor and can be adjusted to specific requirements.

The "doxygen.sh" shell script generates the LAMMPS "doxygen"
documentation.

Detailed instructions can be found in the README file.

tools/doxygen/README

+==========================
+doxygen documentation tool
+==========================
+
+The tools/doxygen directory contains additional tools that assist development oriented users in creating source code documentation of LAMMPS with the "doxygen" documentation generation platform in a user defined format flavor.
+
+
+==================
+Directory contents
+==================
+
+The tools/doxygen directory comprises the following files:
+
+ - "doxygen.sh" = Bash shell script for creating the LAMMPS documentation with
+   the "doxygen" documentation platform
+
+ - "Doxyfile.lammps" = Flavor definition for documentation of LAMMPS with the
+   "doxygen" documentation platform. During processing, a new file named
+   "Doxyfile" is produced that should not be edited.
+
+ - "Developer.dox.lammps" = Transcripted version of the developer documentation
+   in "doxygen" (markdown markup language) format in order to help understanding
+   the code working principles within the "doxygen" documentation context.
+   During processing, a new file named "Developer.dox" is produced that should
+   not be edited.
+
+
+=====================
+Building instructions
+=====================
+
+The "doxygen" documentation is generated by executing the "doxygen.sh" bash
+script from the lammps root directory.
+
+  user@host:/.../lammps-root> bash tools/doxygen/doxygen.sh
+
+The "doxygen.sh" script has no user executable rights and must be launched
+with explicit activation of a "bash" shell.
+
+Before the "doxygen" documentation can be generated, all pre-selected LAMMPS
+packages are deselected in order to avoid duplicates in the source code.
+For this, the "doxygen.sh" bash script implicitly includes the command
+
+  user@host:/.../lammps-root/src> make no-all
+
+This could disturb an already configured production environment.
+For this reason, the generation of the "doxygen" documentation for LAMMPS
+is best recommended on a freshly cloned copy of the git repository and
+selecting the desired development branch:
+
+  user@host:/.../anypath> git clone https://github.com/lammps/lammps.git
+  user@host:/.../anypath> cd lammps
+  user@host:/.../anypath/lammps> git checkout your-desired-branch
+  user@host:/.../anypath/lammps> tools/doxygen/doxygen.sh
+
+The generated "doxygen" documentation {does not include the additional packages}
+in the "lib" directory, as many of these packages themselves are at least partially
+documented in doxygen format and their adverse documentation instructions
+could disturb the building process. For this reason, the directory "src/USER-ATC"
+must also be excluded. However, the "USER-ATC" package itself is already profoundly
+documented with the "doxygen" platform.
+
+The files "Doxyfile" and "Developer.dox" are automatically generated in the
+tools/doxygen directory during the build process.
+
+To the conversion of images the "fig2dev" package must be available on the
+development system.
+
+
+=======
+Results
+=======
+
+The doxygen documentation for LAMMPS is created in the following directories:
+
+  "tools/doxygen/doc" = LAMMPS documetation in "doxygen" html format.
+  In order to read the html documentation, start with loading the "index.html"
+  file into an internet browser of choice from this directory. The generation
+  of other formats (pdf, docbook, rtf or man) is disabled by default but can be
+  activated if needed. In order to get the desired formatting results, some
+  adjustments in the configuration file "Doxyfile.lammps" may be required.
+
+  "tools/doxygen/doc/Manual" = an image copy of the the vintage LAMMPS
+  documentation for quick reference browsing. In order to read the vintage
+  LAMMPS documentation, start with loading the "Manual.html" file into an
+  internet browser of choice from this directory. The doxygen documentation
+  integrates the vintage LAMMPS documentation with appropriate links.
+
+
+===============
+Important notes
+===============
+
+The "doxygen.sh" bash script builds the vintage LAMMPS documentation and makes
+an image copy of it into the directory "tools/doxygen/doc/Manual". The generation
+of the vintage LAMMPS documentation must perfectly work for the "html" format.
+In order to fulfill this requirement, additional development packages may have 
+to be available on the build platform.
+
+
+======================
+Latest doxygen version
+======================
+
+The "Doxyfile.lammps" configuration file is using the "doxygen" version 1.8.15.
+If the latest features of the "doxygen" documentation platform are desired,
+it can be downloaded and built with the following steps:
+
+  user@host:/.../anypath> git clone https://github.com/doxygen/doxygen.git
+  user@host:/.../anypath> cd doxygen
+  user@host:/.../anypath/doxygen> mkdir build
+  user@host:/.../anypath/doxygen/build> cd build
+  user@host:/.../anypath/doxygen/build> cmake -G "Unix Makefiles" -Dbuild_doc=ON -DCMAKE_INSTALL_PREFIX=/.../installpath ../
+  user@host:/.../anypath/doxygen/build> make -j 8
+  user@host:/.../anypath/doxygen/build> make docs
+  user@host:/.../anypath/doxygen/build> make install
+
+The compilation of the "doxygen" documentation platform uses the "cmake" build system.
+
+After a successful build process, the "doxygen" executable can be found under the path
+
+user@host:/.../installpath/bin/doxygen
+
+With this steps, the most up-to-date version of the "doxygen" documentation system
+can be obtained. Please note that in order to define different compilation flavors,
+many other build options are available than mentioned above. With appropriate
+adjustments in the "Doxyfile.lammps" configuration file, different documentation
+flavors and representations can be created. The use of an up-do-date "doxygen"
+version is highly recommended for including the latest formatting and compatibility
+features.
+
+To the generation of the "doxygen" documentation in the "make docs" step above,
+additional development packages and numerous latex packages may have to be available
+on the build platform.
+
+Depending on the selected installation path, in the "make install" step root rights
+could be required for successful installation.
+
+The maintenance of the "doxygen" documentation platform continuously includes new
+features, bugfixes and adjustments to advanced coding standards or changing operating
+system platform requirements. The maintenance can be carried out with the outlined
+build procedure after merging the latest commits from the official "doxygen" git
+repository into its local copy (git fetch and git merge or git pull).
+
+
+========================
+Authoring and maintainer
+========================
+
+
+The tool is authored by Nandor Tamaskovics, numericalfreedom at googlemail.com.
+
+
+===============
+Acknowledgement
+===============
+
+The effort for the development of the "doxygen" documentation platform is greatly acknowledged to Dimitri van Heesch (see also http://doxygen.org).

tools/doxygen/doxygen.sh

+#!/bin/bash
+
+LAMMPSBASE=${PWD} ;
+LAMMPSSRC="${LAMMPSBASE}/src" ;
+LAMMPSDOC="${LAMMPSBASE}/doc" ;
+LAMMPSDOCHTML="${LAMMPSDOC}/html" ;
+LAMMPSDEVELOPERDOC="${LAMMPSBASE}/doc/src/Developer" ;
+LAMMPSDOCTMP="/tmp/lammps-docs-*" ;
+LAMMPSDOCMAKE="${LAMMPSDOC}/Makefile" ;
+LAMMPSDOXYGEN="${LAMMPSBASE}/tools/doxygen" ;
+LAMMPSDOXYGENDOC="${LAMMPSDOXYGEN}/doc" ;
+LAMMPSDOXYGENDOCMANUAL="${LAMMPSDOXYGEN}/doc/html/Manual" ;
+
+LAMMPSDOXYFILE=${LAMMPSDOXYGEN}/Doxyfile.lammps ;
+DOXYFILE=${LAMMPSDOXYGEN}/Doxyfile ;
+
+LAMMPSDEVELOPERDOXFILE=${LAMMPSDOXYGEN}/Developer.dox.lammps ;
+DEVELOPERDOXFILE=${LAMMPSDOXYGEN}/Developer.dox ;
+
+FIG2DEV=`which fig2dev` ;
+DOXYGEN=`which doxygen` ;
+
+
+error=0;
+
+
+if [[ -d ${LAMMPSSRC} && -d ${LAMMPSDEVELOPERDOC} && -d ${LAMMPSDOC} && -f ${LAMMPSDOCMAKE} && -d ${LAMMPSDOXYGEN} && -f ${LAMMPSDOXYFILE} ]] ;
+ then
+   cd ${LAMMPSSRC} ;
+   make no-all ;
+   cd ${LAMMPSBASE} ;
+ else
+  error=1 ;
+  echo "Cannot configure LAMMPS sources - Please run doxygen.sh from the LAMMPS root directory."
+ fi ;
+
+
+if [ ${error} == 0 ] ;
+  then
+    if [[ ! -x ${FIG2DEV} ]] ;
+      then
+        error=1 ;
+        echo "${FIG2DEV} not found - Please install ${FIG2DEV} for Your operating system." ;
+      fi ;
+  fi ;
+
+
+if [ ${error} == 0 ] ;
+  then
+    if [[ -d ${LAMMPSDEVELOPERDOC} ]] ;
+      then
+        ${FIG2DEV} -L png ${LAMMPSDEVELOPERDOC}/classes.fig > tools/doxygen/classes.png ;
+        ${FIG2DEV} -L eps ${LAMMPSDEVELOPERDOC}/classes.fig > tools/doxygen/classes.eps ;
+      else
+        error=1 ;
+        echo "LAMMPS developer documentation not found - Please control Your LAMMPS installation." ;
+      fi;
+  fi;
+
+
+if [ ${error} == 0 ] ;
+  then
+    if [[ ! -x ${DOXYGEN} ]] ;
+      then
+        error=1;
+        echo "doxygen not found - Please install doxygen for Your operating system." ;
+      fi ;
+  fi ;
+
+
+if [ ${error} == 0 ] ;
+  then
+    if [[ -d ${LAMMPSSRC} && -f ${LAMMPSDOXYFILE} && -f ${LAMMPSDEVELOPERDOXFILE} ]] ;
+      then
+        ICS=' ';
+        read -r -a array < ${LAMMPSSRC}/version.h ;
+        version=`echo ${array[2]} ${array[3]} ${array[4]} | sed s/\"//g`;
+        cp -av ${LAMMPSDOXYFILE} ${DOXYFILE} ;
+        sed -i "s/LAMMPS_VERSION/${version}/g"  ${DOXYFILE} ;
+        cp -av ${LAMMPSDEVELOPERDOXFILE} ${DEVELOPERDOXFILE} ;
+        sed -i "s/LAMMPS_VERSION/${version}/g"  ${DEVELOPERDOXFILE} ;
+        ${DOXYGEN} ${DOXYFILE} ;
+      else
+        echo "Doxyfile prototype not found - Please control Your LAMMPS installation." ;
+      fi ;
+  fi ;
+
+
+if [ ${error} == 0 ] ;
+  then
+    if [[ -d ${LAMMPSDOC} && -f ${LAMMPSDOCMAKE} ]] ;
+      then
+        cd ${LAMMPSDOC} ;
+        if [ -d ${LAMMPSDOCTMP} ] ;
+         then
+          rm -vrf ${LAMMPSDOCTMP} ;
+         fi ;
+        make clean ;
+        make html ;
+        make pdf ;
+        cd ${LAMMPSBASE} ;
+      echo "${LAMMPSDOC} exists." ;
+    else
+      error=1 ;
+      echo "Cannot build LAMMPS native documentation - Please run doxygen.sh from the LAMMPS root directory." ;
+    fi ;
+  fi ;
+
+
+if [ ${error} == 0 ] ;
+  then
+    if [[ ${error} == 0 && -d ${LAMMPSDOCHTML} ]] ;
+      then
+        if [ -d ${LAMMPSDOXYGENDOCMANUAL} ] ;
+          then
+            rm -vrf ${LAMMPSDOXYGENDOCMANUAL} ;
+            echo "${LAMMPSDOXYGENDOCMANUAL} removed." ;
+          fi ;
+          cp -av ${LAMMPSDOCHTML} ${LAMMPSDOXYGENDOCMANUAL} ;
+	  cp -av ${LAMMPSDOC}/*.pdf ${LAMMPSDOXYGENDOCMANUAL} ;
+          echo "${LAMMPSDOXYGENDOCMANUAL} copied." ;
+        else
+          error=1 ;
+          echo "Cannot include LAMMPS native documentation into the doxygen documentation - Please run doxygen.sh from the LAMMPS root directory." ;
+    fi ;
+  fi ;
+