Added toc to each docs page and Makefile update target

Makefile

@@ -134,6 +134,10 @@ iwyu_fixes: debug
 	python3 $(shell which fix_includes.py) -h --re_only="${PWD}/src/.*" < debug/iwyu.out
 	python3 $(shell which fix_includes.py) -h --re_only="${PWD}/tests/.*" < debug/iwyu.out
 
+.PHONY: docs
+docs:
+	make -C docs toc
+
 .PHONY: fedora_36
 fedora_36:
 	mkdir -p packaging/_BUILD/fedora/36

docs/Makefile

@@ -0,0 +1,37 @@
+# docs/Makefile
+#
+# Copyright (c) 2021-2023 Bartek Kryza <bkryza@gmail.com>
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+
+UPDATE_TOC := markdown-toc  --bullets "*" -i
+
+.PHONY: toc
+toc:
+		$(UPDATE_TOC) class_diagrams.md
+		$(UPDATE_TOC) comment_decorators.md
+		$(UPDATE_TOC) common_options.md
+		$(UPDATE_TOC) configuration_file.md
+		$(UPDATE_TOC) diagram_filters.md
+		$(UPDATE_TOC) doxygen_integration.md
+		$(UPDATE_TOC) include_diagrams.md
+		$(UPDATE_TOC) installation.md
+		$(UPDATE_TOC) interactive_svg_diagrams.md
+		$(UPDATE_TOC) jinja_templates.md
+		$(UPDATE_TOC) package_diagrams.md
+		$(UPDATE_TOC) quick_start.md
+		$(UPDATE_TOC) sequence_diagrams.md
+		$(UPDATE_TOC) test_cases.md
+		$(UPDATE_TOC) troubleshooting.md
+

docs/README.md

@@ -1,6 +1,5 @@
 # Documentation
 
-
 * [Quick start](./quick_start.md)
 * [Installation](./installation.md)
 * Generating diagrams

docs/class_diagrams.md

@@ -1,5 +1,18 @@
 # Generating class diagrams
 
+<!-- toc -->
+
+* [Classes and their properties](#classes-and-their-properties)
+  * [Excluding private or protected members from the diagram](#excluding-private-or-protected-members-from-the-diagram)
+* [Relationships](#relationships)
+  * [Relationships to classes in containers or smart pointers](#relationships-to-classes-in-containers-or-smart-pointers)
+* [Inheritance diagrams](#inheritance-diagrams)
+* [Namespaces as packages](#namespaces-as-packages)
+* [Class context diagram](#class-context-diagram)
+* [Disabling dependency relationships](#disabling-dependency-relationships)
+
+<!-- tocstop -->
+
 The minimal config required to generate a class diagram is presented below:
 ```yaml
 # Path to the directory where `compile_commands.json` can be found

docs/comment_decorators.md

@@ -1,5 +1,14 @@
 # Comment decorators
 
+<!-- toc -->
+
+* [`note`](#note)
+* [`skip` and `skiprelationship`](#skip-and-skiprelationship)
+* [`composition`, `association` and `aggregation`](#composition-association-and-aggregation)
+* [`style`](#style)
+
+<!-- tocstop -->
+
 `clang-uml` provides a set of in-comment directives, called decorators, which allow custom control over
 generation of UML diagrams from C++ and overriding default inference rules for relationships.
 
@@ -82,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
 

docs/common_options.md

@@ -1,5 +1,14 @@
 # Common diagram generation options
 
+<!-- toc -->
+
+* [Overall configuration file structure](#overall-configuration-file-structure)
+* [Translation unit glob patterns](#translation-unit-glob-patterns)
+* [PlantUML custom directives](#plantuml-custom-directives)
+* [Adding debug information in the generated diagrams](#adding-debug-information-in-the-generated-diagrams)
+
+<!-- tocstop -->
+
 ## Overall configuration file structure
 By default, `clang-uml` will look for file `.clang-uml` in the projects directory and read all diagrams definitions
 from it. The file must be specified in YAML and it's overall structure is as follows:

docs/configuration_file.md

@@ -1,5 +1,13 @@
 # Configuration file reference
 
+<!-- toc -->
+
+* [Top level options](#top-level-options)
+  * [Diagram options](#diagram-options)
+* [Example complete config](#example-complete-config)
+
+<!-- tocstop -->
+
 ## Top level options
 * `compilation_database_dir` - path to the directory containing `compile_commands.json`
 * `output_directory` - path to the directory where PlantUML diagrams will be generated

docs/diagram_filters.md

@@ -1,5 +1,17 @@
 # Diagram filters
 
+<!-- toc -->
+
+* [`namespaces`](#namespaces)
+* [`elements`](#elements)
+* [`context`](#context)
+* [`relationships`](#relationships)
+* [`subclasses`](#subclasses)
+* [`specializations`](#specializations)
+* [`dependants` and `dependencies`](#dependants-and-dependencies)
+
+<!-- tocstop -->
+
 Diagram filters are at the core of generating diagrams with `clang-uml`, as they allow to fine tune the scope
 of each diagram, and thus provide you with a several small, but readable diagrams instead of a single huge diagram
 that cannot be effectively browsed, printed or included in an online documentation of your project.

docs/doxygen_integration.md

@@ -1,5 +1,11 @@
 # Doxygen integration
 
+<!-- toc -->
+
+
+
+<!-- tocstop -->
+
 `clang-uml` diagrams can be easily added to the Doxygen documentation using the image tag, however
 [Doxygen](https://www.doxygen.nl/index.html) does not support the `clang-uml` specific commands.
 

docs/include_diagrams.md

@@ -1,5 +1,11 @@
 # Generating include diagrams
 
+<!-- toc -->
+
+* [Tracking system headers directly included by projects files](#tracking-system-headers-directly-included-by-projects-files)
+
+<!-- tocstop -->
+
 Include diagrams allow to document the include dependencies among different parts of the project. This can be very useful
 for instance to detect that a file was included from a module directory, on which specific part of the project
 should not ever depend.

docs/installation.md

@@ -1,5 +1,19 @@
 # Installation
 
+<!-- toc -->
+
+* [Distribution packages](#distribution-packages)
+  * [Ubuntu](#ubuntu)
+  * [Fedora](#fedora)
+  * [Conda](#conda)
+* [Building from source](#building-from-source)
+  * [Linux](#linux)
+  * [macos](#macos)
+  * [Windows](#windows)
+    * [Visual Studio native build](#visual-studio-native-build)
+
+<!-- tocstop -->
+
 ### Distribution packages
 
 #### Ubuntu

docs/interactive_svg_diagrams.md

@@ -1,5 +1,11 @@
 # Interactive SVG diagrams
 
+<!-- toc -->
+
+
+
+<!-- tocstop -->
+
 `clang-uml` in combination with PlantUML's link generation in diagrams allows to generate interactive diagrams,
 where clicking on any class, method or call expression can direct the user directly to the source code or some other
 diagram or document available online.

docs/jinja_templates.md

@@ -1,4 +1,13 @@
 # Template engine
+
+<!-- toc -->
+
+* [Accessing comment content](#accessing-comment-content)
+  * [`plain` comment parser](#plain-comment-parser)
+  * [`clang` comment parser](#clang-comment-parser)
+
+<!-- tocstop -->
+
 `clang-uml` integrates [inja](https://github.com/pantor/inja) template engine, with several
 additional functions which can be used in textual directives within the configuration files,
 notes and to generate links and tooltips in diagrams.

docs/package_diagrams.md

@@ -1,5 +1,11 @@
 # Generating package diagrams
 
+<!-- toc -->
+
+
+
+<!-- tocstop -->
+
 Package diagrams are simple diagrams which can be useful to determine the high level structure of a C++ project, 
 by rendering all projects namespaces as UML packages and their interdependencies.
 

docs/quick_start.md

@@ -1,5 +1,11 @@
 # Quick start
 
+<!-- toc -->
+
+
+
+<!-- tocstop -->
+
 To add an initial class diagram to your project, follow these steps:
 
 1. Enter your projects top level directory and run:

docs/sequence_diagrams.md

@@ -1,5 +1,15 @@
 # Generating sequence diagrams
 
+<!-- toc -->
+
+* [Sequence diagram overview](#sequence-diagram-overview)
+* [Specifying diagram entry point](#specifying-diagram-entry-point)
+* [Grouping free functions by file](#grouping-free-functions-by-file)
+* [Lambda expressions in sequence diagrams](#lambda-expressions-in-sequence-diagrams)
+* [Customizing participants order](#customizing-participants-order)
+
+<!-- tocstop -->
+
 The minimal config required to generate a sequence diagram is presented below:
 ```yaml
 # Path to the directory where `compile_commands.json` can be found

docs/test_cases.md

@@ -1,4 +1,15 @@
 # Test cases index
+
+<!-- toc -->
+
+* [Class diagrams](#class-diagrams)
+* [Sequence diagrams](#sequence-diagrams)
+* [Package diagrams](#package-diagrams)
+* [Include diagrams](#include-diagrams)
+* [Configuration diagrams](#configuration-diagrams)
+
+<!-- tocstop -->
+
 ## Class diagrams
  * [t00002](./test_cases/t00002.md) - Basic class inheritance
  * [t00003](./test_cases/t00003.md) - Class field and methods

docs/troubleshooting.md

@@ -1,5 +1,17 @@
 # Troubleshooting
 
+<!-- toc -->
+
+* [General issues](#general-issues)
+  * [Diagram generated with PlantUML is cropped](#diagram-generated-with-plantuml-is-cropped)
+* [Class diagrams](#class-diagrams)
+  * ["fatal error: 'stddef.h' file not found"](#fatal-error-stddefh-file-not-found)
+* [Sequence diagrams](#sequence-diagrams)
+  * [Generated diagram is empty](#generated-diagram-is-empty)
+  * [Generated diagram contains several empty control blocks or calls which should not be there](#generated-diagram-contains-several-empty-control-blocks-or-calls-which-should-not-be-there)
+
+<!-- tocstop -->
+
 ## General issues
 ### Diagram generated with PlantUML is cropped
 When generating diagrams with PlantUML without specifying an output file format, the default is PNG.