lammps/tools/doxygen

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