Tools for LAMMPS documentation with the "doxygen" documentation platform

==========================

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

#!/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 ;