forked from lijiext/lammps
159 lines
6.6 KiB
Plaintext
159 lines
6.6 KiB
Plaintext
==========================
|
|
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 documentation 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).
|