diff options
author | Gerd Heber <gheber@hdfgroup.org> | 2021-11-23 14:05:40 (GMT) |
---|---|---|
committer | GitHub <noreply@github.com> | 2021-11-23 14:05:40 (GMT) |
commit | b9e4deec10cc943a7ecb3ac6bc6bd6695b2f33a0 (patch) | |
tree | 6e9c6b646c9bc28b7e3ff3282b99101edea0508e /doxygen/dox/About.dox | |
parent | 4b9ca8e1f62c36b8ab5eb803b72df2b0b6fed548 (diff) | |
download | hdf5-b9e4deec10cc943a7ecb3ac6bc6bd6695b2f33a0.zip hdf5-b9e4deec10cc943a7ecb3ac6bc6bd6695b2f33a0.tar.gz hdf5-b9e4deec10cc943a7ecb3ac6bc6bd6695b2f33a0.tar.bz2 |
Next batch of Doxygen updates. (#1180)
* Sketch of the H5S life cycle.
* Committing clang-format changes
* Fix H5S_UNLIMITED snafu.
* Updated RM template and RM page.
* Added H5S life cycle.
* Committing clang-format changes
* Added H5T life cycle.
* Committing clang-format changes
* Cleaner layout (?)
* Cleaned the H5F life cycle. Called out unfinished biz.
* Committing clang-format changes
* Remaining life cycle skeletons.
* Committing clang-format changes
* Committing clang-format changes
* Added H5Z life cycle.
* Committing clang-format changes
* Added H5G life cycle.
* Committing clang-format changes
* H5 and H5I life cycle updates.
* Committing clang-format changes
* Added H5PL life cycle.
* Committing clang-format changes
* Added H5L life cycle.
* Committing clang-format changes
* Fix for Chris' comment.
* Add a variable for Doxygen pre-processor definitions.
* Forgot to add the H5M API.
* Clarify the H5Z life cycle.
* Committing clang-format changes
* Add H5Zdevelop.h to Doxygen.in. Added H5I life cycle.
* Committing clang-format changes
* Clarified introduction and fixed missing label declaration.
* Added H5O life cycle.
* Committing clang-format changes
* H5O cleanup, part 1.
* Committing clang-format changes
* Cleaned up some of the endless repetition in H5O.
* Committing clang-format changes
* Cookbook & RFC draft layouts.
* Updated manifest.
* Updated the manifest, the example paths, and sketched the 1st recipe.
* Committing clang-format changes
* Outlined two more recipes.
* Committing clang-format changes
* More recipes and RFCs.
* Committing clang-format changes
* Draft of templatized RFC references.
* Another batch of RFC changes.
* Another batch of RFCs.
* Fixed reference.
* RFCs in reverse chronological order.
* First cut of RFCs.
* Fixed reference.
* Updated recipes.
* Updated recipes.
* More RFCs.
* Updated D*PL comments.
* Added H5P descriptions.
* Committing clang-format changes
* H5R life-cycle snapshot.
* Committing clang-format changes
* H5R life-cycle. Added line numbers to life-cycle examples.
* Committing clang-format changes
* Fixed formatting for H5Dchunk_iter().
* Added comment on collective mode requirement w/ compression.
* Simplified API compat. macro dox.
* More API vers. updates.
* Hide the async macro entrails.
* Latest VFD SWMR RFC.
* Create a tag file for permalinks.
* Added TODOs for metadoc.
* Removed duplication.
* Revised RM landing page.
* Trimmed more duplication.
* Committing clang-format changes
* Revised H5D.
* Committing clang-format changes
* Updated survey link.
* Added Doxygen RM entry template link.
* Added the "Multi-Thread HDF5" RFC.
* Added DOXYGEN_TAG_FILE.
* Added selection I/O RFC.
* Added the VFD Sub-filing RFC.
* Updated meta-documentation and added two old presentations.
* Added a few more RFCs (4).
* Fixed MANIFEST.
* Updated meta-documentation.
* Added Filters technical note.
* Fixed MANIFEST.
* Restore the path stripper.
* Experimental full-text search via Google.
* Better full-text search integration.
* Whoops. Forgot this one.
* Oh boy.
* Make CMake happy.
* Added "Debugging HDF5 Applications" technical note.
* Another batch of RFCs.
Co-authored-by: github-actions <41898282+github-actions[bot]@users.noreply.github.com>
Diffstat (limited to 'doxygen/dox/About.dox')
-rw-r--r-- | doxygen/dox/About.dox | 120 |
1 files changed, 113 insertions, 7 deletions
diff --git a/doxygen/dox/About.dox b/doxygen/dox/About.dox index 32930a8..0b21fcc 100644 --- a/doxygen/dox/About.dox +++ b/doxygen/dox/About.dox @@ -12,12 +12,118 @@ of <em>documentation done right</em>. \section about_documentation Documentation about Documentation -\li \todo Describe how to add a reference or a new RFC -\li \todo Describe how to add an example -\li \todo Describe how to include plain HTML -\li \todo Describe how to add an API macro -\li \todo Describe the custom commands -\li \todo Describe the S3 bucket layout and update routine -\li \todo Link the RM template +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! */
\ No newline at end of file |