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