diff --git a/Documentation/docs/contributing/documenting_itk.md b/Documentation/docs/contributing/documenting_itk.md new file mode 100644 index 00000000000..d4e33ec5bd9 --- /dev/null +++ b/Documentation/docs/contributing/documenting_itk.md @@ -0,0 +1,146 @@ +# Documenting ITK + +The ITK code documentation is available online at https://itk.org/Doxygen/html/. + +By default, the latest released documentation version is displayed, +but documentation for previous versions is available at by choosing the +appropriate version at the bottom of the above page, e.g. +https://itk.org/Doxygen53/html/index.html. + +## Using Doxygen for C++ code + +### Dependencies + +Generating a complete Doxygen documentation requires (besides CMake and +the ITK source code): + +- [**Doxygen**](https://www.doxygen.nl/) +- [**LaTeX**](https://www.latex-project.org/) for formulas + +Preferable: + +- [**Dot**](https://graphviz.org/doc/info/lang.html) from [GraphViz](https://graphviz.org/) + for generating inheritance and dependency graphs. + +## Generating the Doxygen documentation + +Generating the Doxygen documentation for ITK requires: + +- The `BUILD_DOCUMENTATION` CMake flag be turned `ON`. +- Build the project as you would normally do: it will build both the + ITK libraries/binaries and the Doxygen documentation. + +Doxygen will then generate the documentation for enabled modules. So if +you want to generate the complete doxygen documentation you would need +to turn `ON` the `ITK_BUILD_ALL_MODULES` CMake flag. + +### How to document ITK + +Users are referred to [Doxygen's documentation manual](https://www.doxygen.nl/manual/docblocks.html), +and the [command reference list](https://www.doxygen.nl/manual/commands.html) +for detailed instructions. + +Below is a simple example of how to document ITK code. + +#### Classes + +A minimal example to document an ITK class is the following: + +```cpp +/** + * \class MyAwesomeClass + * \brief Short Description of MyAwesomeClass. + * + * Here you can start writing a more detailed documentation for MyAwesomeClass. + * + * To document each template parameters use: + * \tparam T1 documentation for the first type + * \tparam T2 documentation for the second type + * \tparam VDimension documentation about the third template parameter which seems to be related to the Dimension + * + * You can make implicit references to any other ITK class, by just writing their names, e.g. Image, ImageRegion... + * + * You can also set the group(s) the class belongs to: + * \ingroup MySpecialGroupOrModule1 + * \ingroup MySpecialGroupOrModule2 + * + * Or you can create make a dedicated section "see also": + * \sa Image + * \sa ImageRegion + */ + +template< class T1, typename T2, unsigned int VDimension > +class MyAwesomeClass +{ +public: + /** You can directly write the documentation for PixelType */ + typedef PixelType T1; +}; +``` + +The most common Doxygen commands used to document classes in ITK are: + +- [`\class`](https://www.doxygen.nl/manual/commands.html#cmdclass) +- [`\brief`](https://www.doxygen.nl/manual/commands.html#cmdbrief) +- [`\tparam`](http://www.stack.nl/~dimitri/doxygen/commands.html#cmdtparam) +- [`\ingroup`](https://www.doxygen.nl/manual/commands.html#cmdingroup) +- [`\sa`](https://www.doxygen.nl/manual/commands.html#cmdsa) + +#### Methods and functions + +Similar to classes, methods and functions can be documented using +Doxygen commands. + +A minimal example for a method documentation is the following: + +```cpp +/** \brief A short description of Method1. + * + * A more detailed documentation for Method1. + * + * \param[in] iP1 Documentation for the first parameter, an input parameter. + * \param[in] iValue Documentation for the second parameter, an input parameter. + * \param[out] oValue Documentation for the third parameter, an output parameter. + * \param[in,out] ioP2 Documentation for the fourth parameter, an input/output parameter. + * \return Description about the return value. + */ +int Method1(PixelType iP1, unsigned int iValue, unsigned int& oValue, PixelType& ioP2) const +``` + +The most common Doxygen commands used to document methods and functions +in ITK are: + +- [`\param`][https://www.doxygen.nl/manual/commands.html#cmdparam) +- [`\return`][https://www.doxygen.nl/manual/commands.html#cmdreturn) + +### Creating links to ITK examples + +Links to ITK examples can be created using the special +`\sphinx/\endphinx` Doxygen span pair and the `\sphinxexample` command +defined by ITK. + +It is used as, e.g. + +```cpp +/** \class Image + * \brief Templated n-dimensional image class. + * + * (...) + * + * \sphinx + * \sphinxexample{Core/Common/SetPixelValueInOneImage,Set Pixel Value In One Image} + * \sphinxexample{Core/Common/DisplayImage,Display Image} + * \endsphinx + */ +``` + +where the first argument to `\sphinxexample` points to the relative +path of the example at the [ITK Examples source code](https://github.com/InsightSoftwareConsortium/ITKSphinxExamples/tree/master/src), +and the second one being the title of the example in the +`Documentation.rst` file of the example at issue. + +#### Maintaining the documentation + +The documentation is built nightly on the latest ITK commit, and deployed to GitHub pages +at https://insightsoftwareconsortium.github.io/ITKDoxygen/, whose code is maintaned at +https://github.com/InsightSoftwareConsortium/ITKDoxygen. diff --git a/Documentation/docs/contributing/index.md b/Documentation/docs/contributing/index.md index 1319ee1bd22..a2f86e7ddf9 100644 --- a/Documentation/docs/contributing/index.md +++ b/Documentation/docs/contributing/index.md @@ -395,6 +395,7 @@ CDash Dashboard dashboard.md updating_third_party.md data.md +documenting_itk.md upload_binary_data.md module_workflows.md python_packaging.md