1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
|
/** \page About About
\section about_history History
The implementation of this documentation set is based on the fantastic work of the
<a href="https://eigen.tuxfamily.org/index.php?title=Main_Page">Eigen project</a>.
Please refer to their <a href="https://gitlab.com/libeigen/eigen">GitLab repository</a>
and the online version of their
<a href="http://eigen.tuxfamily.org/dox/">Doxygen-based documentation</a>.
Not only does Eigen set a standard as a piece of software, but also as an example
of <em>documentation done right</em>.
\section about_documentation Documentation about Documentation
In this section, we describe common documentation maintenance tasks.
\subsection plain_html Including Plain HTML Pages
The most common use case for this is the inclusion of older documentation.
New documentation should, whenever possible, be created using Doxygen markdown!
Use Doxygen's <a href="https://www.doxygen.nl/manual/commands.html#cmdhtmlinclude"><code>htmlinclude</code></a>
special command to include existing plain HTML pages.
An example from this documentation set can be seen
<a href="https://github.com/HDFGroup/hdf5/blob/develop/doxygen/dox/FileFormatSpec.dox">here</a>.
\subsection new_rm_entry Creating a New Reference Manual Entry
Please refer to the \ref RMT for guidance on how to create a new reference manual entry.
\subsubsection new_example Adding and Referencing API Examples
For each HDF5 module, such as \Code{H5F}, there is an examples source file called
\Code{H5*_examples.c}. For example, the \Code{H5F} API examples are located in
<a href="https://github.com/HDFGroup/hdf5/blob/develop/doxygen/examples/H5F_examples.c">
<code>H5F_examples.c</code></a>. Examples are code blocks marked as Doxygen
<a href="https://www.doxygen.nl/manual/commands.html#cmdsnippet">snippets</a>.
For example, the source code for the H5Fcreate() API sample is located between
the
\verbatim
//! <!-- [create] -->
...
//! <!-- [create] -->
\endverbatim
comments in
<a href="https://github.com/HDFGroup/hdf5/blob/develop/doxygen/examples/H5F_examples.c">
<code>H5F_examples.c</code></a>.
Add a new API example by adding a new code block enclosed between matching
snippet tags. The name of the tag is usually the function name stripped of
the module prefix.
The inclusion of such a block of code can then be triggered via Doxygen's
<a href="https://www.doxygen.nl/manual/commands.html#cmdsnippet"><code>snippet</code></a>
special command. For example, the following markup
\verbatim
* \snippet H5F_examples.c create
\endverbatim
yields
\snippet H5F_examples.c create
\subsubsection api_macro Adding an API Macro
API macros are handled by the <code>api_vers_2, api_vers_3, api_vers_4</code>
custom commands. The numbers indicate the number of potential API function
mappings. For example, H5Acreate() has two potential mappings, H5Acreate1() and
H5Acreate2(). To trigger the creation of a reference manual entry for H5Acreate()
use the following markup:
\verbatim
\api_vers_2{H5Acreate,H5Acreate1,H5Acreate2}
\endverbatim
This yields:
\api_vers_2{H5Acreate,H5Acreate1,H5Acreate2}
\subsection custom_commands Creating Custom Commands
See Doxygen's <a href="https://www.doxygen.nl/manual/custcmd.html">Custom Commands documentation</a>
as a general reference.
All custom commands for this project are located in the
<a href="https://github.com/HDFGroup/hdf5/blob/develop/doxygen/aliases"><tt>aliases</tt></a>
file in the <a href="https://github.com/HDFGroup/hdf5/tree/develop/doxygen"><tt>doxygen</tt></a>
subdirectory of the <a href="https://github.com/HDFGroup/hdf5">main HDF5 repo</a>.
The custom commands are grouped in sections. Find a suitable section for your command or
ask for help if unsure!
\subsection new_rfc Adding a New RFC or Referencing an Existing RFC
For ease of reference, we define custom commands for each RFC in the <tt>RFCs</tt> section
of the
<a href="https://github.com/HDFGroup/hdf5/blob/develop/doxygen/aliases"><tt>aliases</tt></a>
file. For example the custom command \Code{ref_rfc20141210} can be used to insert a
reference to "RFC: Virtual Object Layer". In other words, the markup
\verbatim
\ref_rfc20141210
\endverbatim
yields a clickable link:
\ref_rfc20141210
To add a new RFC, add a custom command for the RFC to the
<a href="https://github.com/HDFGroup/hdf5/blob/develop/doxygen/aliases"><tt>aliases</tt></a>
file. The naming convention for the custom command is \Code{ref_rfcYYYYMMDD},
where \Code{YYYYMMDD} is the ID of the RFC. The URL is composed of the prefix
\verbatim
https://docs.hdfgroup.org/hdf5/rfc/
\endverbatim
and the name of your RFC file, typically, a PDF file, i.e., the full URL would
be
\verbatim
https://docs.hdfgroup.org/hdf5/rfc/my_great_rfc_name.pdf
\endverbatim
\subsection hosting How Do Updates and Changes Get Published?
Currently, the files underlying this documentation website are stored in an
bucket on AWS S3. The top-level bucket is <pre>s3://docs.hdfgroup.org/hdf5/</pre>
There are folders for the <tt>development</tt> branch and all supported release
version.
Talk to your friendly IT-team if you need write access, or you need someone to
push an updated version for you!
\todo Make the publication a GitHub action!
*/
|
