Updated Doxygen docs

Author: bkryza

.gitignore

@@ -25,6 +25,8 @@ docs/diagrams
 docs/doxygen/html
 docs/doxygen/xml
 docs/doxygen/latex
+docs/contributing.md
+docs/changelog.md
 
 coverage*.info
 

CONTRIBUTING.md

@@ -1,8 +1,10 @@
-# Contributing to `clang-uml`
+# Contributing to clang-uml
 
 Thanks for taking interest in `clang-uml`!
 
-> Please, make sure you're ok with [Code of conduct](./CODE_OF_CONDUCT.md) and [LICENSE](./LICENSE.md)
+> Please, make sure you're ok with 
+> [Code of conduct](./CODE_OF_CONDUCT.md)
+> and [LICENSE](./LICENSE.md)
 
 
 ## If you found a bug
@@ -18,12 +20,12 @@ Thanks for taking interest in `clang-uml`!
   the C++ code which triggers the issue, and in `tests/t00050/test_case.h` write the test checks.
   The test case must be also added manually to `tests/test_cases.cc`:
    ```cpp
-   ...
+   // ...
    #include "t00047/test_case.h"
    #include "t00048/test_case.h"
    #include "t00049/test_case.h"
-   #include "t00050/test_case.h"
-   ...
+   #include "t00050/test_case.h" // <<<
+   // ...
    ```
 
   Finally, create an issue with a link to your branch with the new test case.
@@ -82,8 +84,8 @@ Thanks for taking interest in `clang-uml`!
   the feature to ensure we're on the same page as to its purpose and possible implementation
 * Next, implement the feature, please try to adapt to the overall code style:
   * 80-character line width
-  * snakes over camels
-  * use `make format` before submitting PR to ensure consistent formatting
+  * snakes not camels
+  * use `make format` before submitting PR to ensure consistent formatting (requires Docker)
   * use `make tidy` to check if your code doesn't introduce any `clang-tidy` warnings
 * Add test case (or multiple test cases), which cover the new feature
 * Finally, create a pull request!

Doxyfile

@@ -44,7 +44,7 @@ PROJECT_NUMBER         = 0.3.7
 # for a project that appears at the top of each page and should give viewer a
 # quick idea about the purpose of the project. Keep the description short.
 
-PROJECT_BRIEF          = C++ UML diagram generator based on Clang
+PROJECT_BRIEF          = C++ to UML diagram generator based on Clang
 
 # With the PROJECT_LOGO tag one can specify a logo or an icon that is included
 # in the documentation. The maximum height of the logo should not exceed 55
@@ -781,7 +781,7 @@ FILE_VERSION_FILTER    =
 # DoxygenLayout.xml, doxygen will parse it automatically even if the LAYOUT_FILE
 # tag is left empty.
 
-LAYOUT_FILE            =
+LAYOUT_FILE            = docs/doxygen/layout-clang-uml.xml
 
 # The CITE_BIB_FILES tag can be used to specify one or more bib files containing
 # the reference definitions. This must be a list of .bib files. The .bib
@@ -1013,7 +1013,9 @@ EXAMPLE_RECURSIVE      = NO
 # that contain images that are to be included in the documentation (see the
 # \image command).
 
-IMAGE_PATH             = docs/diagrams
+IMAGE_PATH             = docs/img
+IMAGE_PATH             += docs/diagrams
+IMAGE_PATH             += docs/test_cases
 
 # The INPUT_FILTER tag can be used to specify a program that doxygen should
 # invoke to filter for each input file. Doxygen will invoke the filter program
@@ -1305,9 +1307,9 @@ HTML_EXTRA_FILES       = thirdparty/doxygen-awesome-css/doxygen-awesome-interact
 HTML_EXTRA_FILES       += thirdparty/doxygen-awesome-css/doxygen-awesome-paragraph-link.js
 HTML_EXTRA_FILES       += thirdparty/doxygen-awesome-css/doxygen-awesome-fragment-copy-button.js
 HTML_EXTRA_FILES       += thirdparty/doxygen-awesome-css/doxygen-awesome-tabs.js
-HTML_EXTRA_FILES       += CONTRIBUTING.md
 HTML_EXTRA_FILES       += docs/doxygen/highlight.min.js
-HTML_EXTRA_FILES       += docs/doxygen/solarized-light.min.css
+HTML_EXTRA_FILES       += docs/doxygen/github.min.css
+HTML_EXTRA_FILES       += docs/img/github-mark.svg
 
 # The HTML_COLORSTYLE_HUE tag controls the color of the HTML output. Doxygen
 # will adjust the colors in the style sheet and background images according to

Makefile

@@ -139,8 +139,10 @@ docs:
 	make -C docs toc
 
 .PHONY: doxygen
-doxygen:
-	doxygen
+doxygen: docs
+	cp CONTRIBUTING.md docs/contributing.md
+	cp CHANGELOG.md docs/changelog.md
+	../doxygen/_build/bin/doxygen
 
 .PHONY: fedora/%
 fedora/%:

docs/README.md

@@ -9,15 +9,20 @@ legacy code. The configuration file or files for `clang-uml` define the
 types and contents of each generated diagram.
 The diagrams can be generated in [PlantUML](https://plantuml.com) and JSON formats.
 
+Example sequence diagram generated using `clang-uml` from [this code](https://github.com/bkryza/clang-uml/blob/master/tests/t20029/t20029.cc):
+![Sample sequence diagram](test_cases/t20029_sequence.svg)
+
 `clang-uml` currently supports C++ up to version 17 with partial support for C++ 20.
 
 To see what `clang-uml` can do, checkout the diagrams generated for unit
 test cases [here](./test_cases.md) or examples in
 [clang-uml-examples](https://github.com/bkryza/clang-uml-examples) repository.
 
+These pages provide both user and developer documentation.
+
 * [Quick start](./quick_start.md)
 * [Installation](./installation.md)
-* Generating diagrams
+* **Generating diagrams**
   * [Common options](./common_options.md)
   * [Generator types](./generator_types.md)
   * [Class diagrams](./class_diagrams.md)
@@ -33,6 +38,8 @@ test cases [here](./test_cases.md) or examples in
 * [Doxygen integration](./doxygen_integration.md)
 * [Test cases documentation](./test_cases.md)
 * [Troubleshooting](./troubleshooting.md)
-* Development
+* [Changelog](./changelog.md)
+* [License](./license.md)
+* **Development**
   * [Architecture](./architecture.md)
-  * [Contributing](../CONTRIBUTING.md)
+  * [Contributing](./contributing.md)

docs/architecture.md

@@ -0,0 +1,2 @@
+# Architecture
+

docs/comment_decorators.md

@@ -2,10 +2,10 @@
 
 <!-- toc -->
 
-* [`note`](#note)
-* [`skip` and `skiprelationship`](#skip-and-skiprelationship)
-* [`composition`, `association` and `aggregation`](#composition-association-and-aggregation)
-* [`style`](#style)
+* ['note'](#note)
+* ['skip' and 'skiprelationship'](#skip-and-skiprelationship)
+* ['composition', 'association' and 'aggregation'](#composition-association-and-aggregation)
+* ['style'](#style)
 
 <!-- tocstop -->
 
@@ -27,7 +27,7 @@ The optional `:<diagram_name>` suffix will apply this decorator only to a specif
 
 Currently, the following decorators are supported.
 
-## `note`
+## 'note'
 
 This decorator allows to specify directly in the code comments that should be included in the generated diagrams.
 
@@ -91,7 +91,7 @@ generates the following class diagram:
 
 ![note](./test_cases/t00028_class.svg)
 
-## `skip` and `skiprelationship`
+## 'skip' and 'skiprelationship'
 This decorator allows to skip the specific classes or methods from the diagrams, for instance the following code:
 ```cpp
 
@@ -145,7 +145,7 @@ generates the following diagram:
 
 ![skip](./test_cases/t00029_class.svg)
 
-## `composition`, `association` and `aggregation`
+## 'composition', 'association' and 'aggregation'
 
 These decorators allow to specify explicitly the type of relationship within a class diagram that should be
 generated for a given class member. For instance the following code:
@@ -190,7 +190,7 @@ generates the following diagram:
 ![skip](./test_cases/t00030_class.svg)
 
 
-## `style`
+## 'style'
 This decorator allows to specify in the code specific styles for diagram elements, for instance:
 
 ```cpp

docs/common_options.md

@@ -7,9 +7,9 @@
 * [PlantUML custom directives](#plantuml-custom-directives)
 * [Adding debug information in the generated diagrams](#adding-debug-information-in-the-generated-diagrams)
 * [Resolving include path and compiler flags issues](#resolving-include-path-and-compiler-flags-issues)
-  * [Use `--query-driver` command line option](#use---query-driver-command-line-option)
+  * [Use '--query-driver' command line option](#use---query-driver-command-line-option)
   * [Manually add and remove compile flags from the compilation database](#manually-add-and-remove-compile-flags-from-the-compilation-database)
-  * [Using `CMAKE_CXX_IMPLICIT_INCLUDE_DIRECTORIES`](#using-cmake_cxx_implicit_include_directories)
+  * [Using 'CMAKE_CXX_IMPLICIT_INCLUDE_DIRECTORIES'](#using-cmake_cxx_implicit_include_directories)
 
 <!-- tocstop -->
 
@@ -18,14 +18,17 @@ By default, `clang-uml` will look for file `.clang-uml` in the projects director
 from it. The file must be specified in YAML and it's overall structure is as follows:
 
 ```yaml
-<common options for all diagrams>
+# common options for all diagrams
+...
 diagrams:
-  <first diagram name>:
-    type: [class|sequence|package|include]
-    <diagram specific options>
-  <second diagram name>:
-    type: [class|sequence|package|include]
-    <diagram specific options>
+  first_diagram_name>:
+    type: class|sequence|package|include
+    # diagram specific options
+    ...
+  second_diagram_name:
+    type: class|sequence|package|include
+    # diagram specific options
+    ...
   ...
 ```
 
@@ -116,7 +119,7 @@ These errors can be overcome, by ensuring that the Clang parser has the correct
 include paths to analyse your code base on the given platform. `clang-uml`
 provides several mechanisms to resolve this issue:
 
-### Use `--query-driver` command line option
+### Use '--query-driver' command line option
 
 > This option is not available on Windows.
 
@@ -133,7 +136,7 @@ system, when generating diagrams for an embedded project and providing
 `arm-none-eabi-gcc` as driver:
 
 ```bash
-$ clang-uml --query-driver arm-none-eabi-gcc
+clang-uml --query-driver arm-none-eabi-gcc
 ```
 
 the following options are appended to each command line after `argv[0]` of the
@@ -148,7 +151,7 @@ already as `argv[0]` in your `compile_commands.json`, you can simply invoke
 `clang-uml` as:
 
 ```bash
-$ clang-uml --query-driver .
+clang-uml --query-driver .
 ```
 
 however please make sure that the `compile_commands.json` contain a command,
@@ -173,11 +176,11 @@ remove_compile_flags:
 These options can be also passed on the command line, for instance:
 
 ```bash
-$ clang-uml --add-compile-flag -I/opt/my_toolchain/include \
-            --remove-compile-flag -I/usr/include ...
+clang-uml --add-compile-flag -I/opt/my_toolchain/include \
+          --remove-compile-flag -I/usr/include ...
 ```
 
-### Using `CMAKE_CXX_IMPLICIT_INCLUDE_DIRECTORIES`
+### Using 'CMAKE_CXX_IMPLICIT_INCLUDE_DIRECTORIES'
 Yet another option, for CMake based projects, is to use the following CMake option:
 
 ```cmake

docs/diagram_templates.md

@@ -88,7 +88,7 @@ clang-uml --show-template parents_hierarchy_tmpl
 users configuration file defines another template with a name which already
 exists as built-in template it will override the predefined templates.
 
-Currently the following templates are built-in:
+Currently, the following templates are built-in:
 * `parents_hierarchy_tmpl` - generate inheritance hierarchy diagram including
    parents of a specified class
 * `subclass_hierarchy_tmpl` - generate inheritance hierarchy diagram including

docs/doxygen/github.min.css

@@ -9,7 +9,7 @@
 <!-- BEGIN opengraph metadata -->
 <meta property="og:title" content="clang-uml" />
 <meta property="og:image" content="$relpath^clang-uml-logo.svg" />
-<meta property="og:description" content="C++ UML diagram generator based on Clang." />
+<meta property="og:description" content="C++ to UML diagram generator based on Clang." />
 <meta property="og:url" content="https://clang-uml.github.io/" />
 <!-- END opengraph metadata -->
 
@@ -22,31 +22,35 @@
 <!--<script type="text/javascript" src="$relpath^doxygen-awesome-darkmode-toggle.js"></script>-->
 <script type="text/javascript" src="$relpath^doxygen-awesome-fragment-copy-button.js"></script>
 <script type="text/javascript" src="$relpath^doxygen-awesome-paragraph-link.js"></script>
-<script type="text/javascript" src="$relpath^doxygen-awesome-interactive-toc.js"></script>
-<script type="text/javascript" src="$relpath^doxygen-awesome-tabs.js"></script>
-<script type="text/javascript" src="$relpath^toggle-alternative-theme.js"></script>
+<!--<script type="text/javascript" src="$relpath^doxygen-awesome-interactive-toc.js"></script>-->
+<!--<script type="text/javascript" src="$relpath^doxygen-awesome-tabs.js"></script>-->
+<!--<script type="text/javascript" src="$relpath^toggle-alternative-theme.js"></script>-->
 <script type="text/javascript">
     DoxygenAwesomeFragmentCopyButton.init()
     // DoxygenAwesomeDarkModeToggle.init()
     DoxygenAwesomeParagraphLink.init()
-    DoxygenAwesomeInteractiveToc.init()
-    DoxygenAwesomeTabs.init()
+    // DoxygenAwesomeInteractiveToc.init()
+    // DoxygenAwesomeTabs.init()
 </script>
 $treeview
 $search
 $mathjax
 <link href="$relpath^$stylesheet" rel="stylesheet" type="text/css" />
 
-<link rel="stylesheet" href="$relpath^solarized-light.min.css">
+<link rel="stylesheet" href="$relpath^github.min.css">
 <script src="$relpath^highlight.min.js"></script>
 <script>
     $(function() {
+        hljs.configure({useBR: false});
         $(".fragment").each(function(i,node) {
             var $node = $(node);
-            $node.html("<pre><code class='" +
-                $node.attr("class")+"'>" +
-                $node.text()+"</code></pre>");
-            hljs.highlightElement(node);
+            // Only apply highlight.js to non-cpp code blocks
+            if (!$node.hasClass("language-cpp")) {
+                $node.html("<pre><code class='" +
+                    $node.attr("class") + "'>" +
+                    $node.text() + "</code></pre>");
+                hljs.highlightElement(node);
+            }
         });
     });
 </script>
@@ -59,35 +63,44 @@
 <!--    <svg viewBox="0 0 250 250" width="70" height="70" style="position: absolute; top: 0; border: 0; right: 0; z-index: 99;" aria-hidden="true">-->
 <!--    <path d="M0,0 L115,115 L130,115 L142,142 L250,250 L250,0 Z"></path><path d="M128.3,109.0 C113.8,99.7 119.0,89.6 119.0,89.6 C122.0,82.7 120.5,78.6 120.5,78.6 C119.2,72.0 123.4,76.3 123.4,76.3 C127.3,80.9 125.5,87.3 125.5,87.3 C122.9,97.6 130.6,101.9 134.4,103.2" fill="currentColor" style="transform-origin: 130px 106px;" class="octo-arm"></path><path d="M115.0,115.0 C114.9,115.1 118.7,116.5 119.8,115.4 L133.7,101.6 C136.9,99.2 139.9,98.4 142.2,98.6 C133.8,88.0 127.5,74.4 143.8,58.0 C148.5,53.4 154.0,51.2 159.7,51.0 C160.3,49.4 163.2,43.6 171.4,40.1 C171.4,40.1 176.1,42.5 178.8,56.2 C183.1,58.6 187.2,61.8 190.9,65.4 C194.5,69.0 197.7,73.2 200.1,77.6 C213.8,80.2 216.3,84.9 216.3,84.9 C212.7,93.1 206.9,96.0 205.4,96.6 C205.1,102.4 203.0,107.8 198.3,112.5 C181.9,128.9 168.3,122.5 157.7,114.1 C157.9,116.9 156.7,120.9 152.7,124.9 L141.0,136.5 C139.8,137.7 141.6,141.9 141.8,141.8 Z" fill="currentColor" class="octo-body"></path></svg></a><style>.github-corner:hover .octo-arm{animation:octocat-wave 560ms ease-in-out}@keyframes octocat-wave{0%,100%{transform:rotate(0)}20%,60%{transform:rotate(-25deg)}40%,80%{transform:rotate(10deg)}}@media (max-width:500px){.github-corner:hover .octo-arm{animation:none}.github-corner .octo-arm{animation:octocat-wave 560ms ease-in-out}}</style>-->
 
-
-<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
-
+<div id="top" style="background-color: gainsboro"><!-- do not remove this div, it is closed by doxygen! -->
 <!--BEGIN TITLEAREA-->
 <div id="titlearea">
 <table cellspacing="0" cellpadding="0">
  <tbody>
  <tr style="height: 56px;">
   <!--BEGIN PROJECT_LOGO-->
-  <td id="projectlogo"><a href="$relpath^index.html"><img alt="Main page" src="$relpath^$projectlogo"/></a></td>
+  <td id="projectlogo">
+      <a href="$relpath^index.html">
+          <img alt="Main page" src="$relpath^$projectlogo"/>
+      </a>
+  </td>
   <!--END PROJECT_LOGO-->
   <!--BEGIN PROJECT_NAME-->
   <td id="projectalign" style="padding-left: 0.5em;">
-   <div id="projectname">$projectname
-   <!--BEGIN PROJECT_NUMBER-->&#160;<span id="projectnumber">$projectnumber</span><!--END PROJECT_NUMBER-->
-   </div>
-   <!--BEGIN PROJECT_BRIEF--><div id="projectbrief">$projectbrief</div><!--END PROJECT_BRIEF-->
+    <div id="projectname">
+       <span id="projectnumber">$projectnumber</span>
+    </div>
+    <div id="projectbrief">$projectbrief</div><!--END PROJECT_BRIEF-->
   </td>
   <!--END PROJECT_NAME-->
   <!--BEGIN !PROJECT_NAME-->
    <!--BEGIN PROJECT_BRIEF-->
-    <td style="padding-left: 0.5em;">
-    <div id="projectbrief">$projectbrief</div>
-    </td>
+<!--  <td style="padding-left: 0.5em;">-->
+<!--    <div id="projectbrief">$projectbrief</div>-->
+<!--  </td>-->
+  <td>
+      <div>
+         <a href="https://github.com/bkryza/clang-uml">
+             <img alt="GitHub" src="$relpath^github-mark.svg"/>
+         </a>
+     </div>
+  </td>
    <!--END PROJECT_BRIEF-->
   <!--END !PROJECT_NAME-->
   <!--BEGIN DISABLE_INDEX-->
    <!--BEGIN SEARCHENGINE-->
-   <td>$searchbox</td>
+     <td>$searchbox</td>
    <!--END SEARCHENGINE-->
   <!--END DISABLE_INDEX-->
  </tr>