Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
add additional documentation section
- Loading branch information
1 parent
b6a5b15
commit 18d2c56
Showing
3 changed files
with
109 additions
and
6 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,103 @@ | ||
| /****************************************************************************** | ||
| * | ||
| * | ||
| * | ||
| * Copyright (C) 1997-2015 by Dimitri van Heesch. | ||
| * | ||
| * Permission to use, copy, modify, and distribute this software and its | ||
| * documentation under the terms of the GNU General Public License is hereby | ||
| * granted. No representations are made about the suitability of this software | ||
| * for any purpose. It is provided "as is" without express or implied warranty. | ||
| * See the GNU General Public License for more details. | ||
| * | ||
| * Documents produced by Doxygen are derivative works derived from the | ||
| * input used in their production; they are not affected by this license. | ||
| * | ||
| */ | ||
| /*! \page additional_documentation Additional Documentation | ||
| \tableofcontents{html,latex} | ||
|
|
||
| \section custom_pages Custom Pages | ||
|
|
||
| \c doxygen can be also be used to create custom pages that are not part of the API of your library/program, | ||
| the purpose of these pages is to enrich your documentation with anything else that you think the user may find useful. (such as this page itself!) | ||
|
|
||
| To create custom pages, use one of the supported the file formats: .dox, .txt, .md. | ||
| Inside such a file doxygen will treat it like any other source file, so one option could be to consider this file as large single doxygen comment. | ||
|
|
||
| \c manual/index.dox | ||
| \code | ||
| /** \mainpage My Library Manual | ||
| - Building | ||
| - Basics | ||
| - Examples | ||
| */ | ||
| \endcode | ||
|
|
||
| You'll note that the `\mainpage` command was used, which tells doxygen to use this page as, well, the main page. For other pages, preface them with the `\page` command. | ||
|
|
||
| By default doxygen will not know about these custom files so we'll need to let it know through the `INPUT` attribute in our Doxyfile, that is with our current configuration, would have this line in our Doxyfile: | ||
|
|
||
| \code | ||
| INPUT = manual/index.dox | ||
| \endcode | ||
|
|
||
| Next, we want to add the instructions on how to build the project, so we create `manual/building/index.dox`. Since we've read a bit more of the documentation and [found out](https://www.doxygen.nl/manual/htmlcmds.html) that doxygen supports a subset of html's elements, so we write the following: | ||
|
|
||
| \code | ||
| /** \page Building | ||
|
|
||
| <h2>linux</h2> | ||
| <p> | ||
| A simple way to build this project is with cmake, clone the repository, cd into the root of the project and run: | ||
| </p> | ||
|
|
||
| <pre> | ||
| <code> | ||
| mkdir my_build | ||
| cmake -S . -B my_build | ||
| cd my_build | ||
| cmake --build . | ||
| </code> | ||
| </pre> | ||
|
|
||
| */ | ||
| \endcode | ||
|
|
||
| \section scaling Scaling Up | ||
|
|
||
| \subsection automatically_adding_files Automatically Adding Files | ||
|
|
||
| At this point we could now go ahead and add `manual/building/index.dox` to our INPUT's with comma separation, but this might become annoying over time as we build up our manual, instead we'll just change it reference our manual folder: | ||
|
|
||
| \code | ||
| INPUT = manual/ | ||
| \endcode | ||
|
|
||
| And set | ||
|
|
||
| \code | ||
| RECURSIVE = YES | ||
| \endcode | ||
|
|
||
| To make sure as we add any subdirectories of the manual as we create more organization and content. | ||
|
|
||
| \subsection treeview Side Panel Treeview | ||
|
|
||
| As your manual scales up, you might want to also have a nice tree view to show you where you are in the manual to stay organized. This is easy enough to set up, turn it on with | ||
|
|
||
| \code | ||
| GENERATE_TREEVIEW = YES | ||
| \endcode | ||
|
|
||
| In your doxyfile. | ||
|
|
||
| You'll recall that our \c manual/index.dox file is pretty bland, without any links pointing anywhere, by using the `\ref` command we can add links between various topics, and doing so will automatically | ||
| start to populate our treeview. | ||
|
|
||
| If you notice that your tree is more like a pile of leaves then you can remedy this by checking out [subpaging](https://www.doxygen.nl/manual/grouping.html#subpaging). | ||
|
|
||
| This disucssion should give you some direction on how to build a scalable manual to enrich your documentation, take this and modify it to suit your needs. | ||
|
|
||
| */ | ||
|
|
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters