Skip to content

Commit 9a527ee

Browse files
bkryzabkryza
committed
Added toc to each docs page and Makefile update target
1 parent c6bb063 commit 9a527ee

18 files changed

+179
-2
lines changed

‎Makefile‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -134,6 +134,10 @@ iwyu_fixes: debug
134134
python3 $(shell which fix_includes.py) -h --re_only="${PWD}/src/.*" < debug/iwyu.out
135135
python3 $(shell which fix_includes.py) -h --re_only="${PWD}/tests/.*" < debug/iwyu.out
136136

137+
.PHONY: docs
138+
docs:
139+
make -C docs toc
140+
137141
.PHONY: fedora_36
138142
fedora_36:
139143
mkdir -p packaging/_BUILD/fedora/36

‎docs/Makefile‎

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
# docs/Makefile
2+
#
3+
# Copyright (c) 2021-2023 Bartek Kryza <[email protected]>
4+
#
5+
# Licensed under the Apache License, Version 2.0 (the "License");
6+
# you may not use this file except in compliance with the License.
7+
# You may obtain a copy of the License at
8+
#
9+
# http://www.apache.org/licenses/LICENSE-2.0
10+
#
11+
# Unless required by applicable law or agreed to in writing, software
12+
# distributed under the License is distributed on an "AS IS" BASIS,
13+
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14+
# See the License for the specific language governing permissions and
15+
# limitations under the License.
16+
17+
18+
UPDATE_TOC := markdown-toc --bullets "*" -i
19+
20+
.PHONY: toc
21+
toc:
22+
$(UPDATE_TOC) class_diagrams.md
23+
$(UPDATE_TOC) comment_decorators.md
24+
$(UPDATE_TOC) common_options.md
25+
$(UPDATE_TOC) configuration_file.md
26+
$(UPDATE_TOC) diagram_filters.md
27+
$(UPDATE_TOC) doxygen_integration.md
28+
$(UPDATE_TOC) include_diagrams.md
29+
$(UPDATE_TOC) installation.md
30+
$(UPDATE_TOC) interactive_svg_diagrams.md
31+
$(UPDATE_TOC) jinja_templates.md
32+
$(UPDATE_TOC) package_diagrams.md
33+
$(UPDATE_TOC) quick_start.md
34+
$(UPDATE_TOC) sequence_diagrams.md
35+
$(UPDATE_TOC) test_cases.md
36+
$(UPDATE_TOC) troubleshooting.md
37+

‎docs/README.md‎

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,5 @@
11
# Documentation
22

3-
43
* [Quick start](./quick_start.md)
54
* [Installation](./installation.md)
65
* Generating diagrams

‎docs/class_diagrams.md‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,18 @@
11
# Generating class diagrams
22

3+
<!-- toc -->
4+
5+
* [Classes and their properties](#classes-and-their-properties)
6+
* [Excluding private or protected members from the diagram](#excluding-private-or-protected-members-from-the-diagram)
7+
* [Relationships](#relationships)
8+
* [Relationships to classes in containers or smart pointers](#relationships-to-classes-in-containers-or-smart-pointers)
9+
* [Inheritance diagrams](#inheritance-diagrams)
10+
* [Namespaces as packages](#namespaces-as-packages)
11+
* [Class context diagram](#class-context-diagram)
12+
* [Disabling dependency relationships](#disabling-dependency-relationships)
13+
14+
<!-- tocstop -->
15+
316
The minimal config required to generate a class diagram is presented below:
417
```yaml
518
# Path to the directory where `compile_commands.json` can be found

‎docs/comment_decorators.md‎

Lines changed: 10 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,14 @@
11
# Comment decorators
22

3+
<!-- toc -->
4+
5+
* [`note`](#note)
6+
* [`skip` and `skiprelationship`](#skip-and-skiprelationship)
7+
* [`composition`, `association` and `aggregation`](#composition-association-and-aggregation)
8+
* [`style`](#style)
9+
10+
<!-- tocstop -->
11+
312
`clang-uml` provides a set of in-comment directives, called decorators, which allow custom control over
413
generation of UML diagrams from C++ and overriding default inference rules for relationships.
514

@@ -82,7 +91,7 @@ generates the following class diagram:
8291
8392
![note](./test_cases/t00028_class.svg)
8493
85-
# `skip` and `skiprelationship`
94+
## `skip` and `skiprelationship`
8695
This decorator allows to skip the specific classes or methods from the diagrams, for instance the following code:
8796
```cpp
8897

‎docs/common_options.md‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,14 @@
11
# Common diagram generation options
22

3+
<!-- toc -->
4+
5+
* [Overall configuration file structure](#overall-configuration-file-structure)
6+
* [Translation unit glob patterns](#translation-unit-glob-patterns)
7+
* [PlantUML custom directives](#plantuml-custom-directives)
8+
* [Adding debug information in the generated diagrams](#adding-debug-information-in-the-generated-diagrams)
9+
10+
<!-- tocstop -->
11+
312
## Overall configuration file structure
413
By default, `clang-uml` will look for file `.clang-uml` in the projects directory and read all diagrams definitions
514
from it. The file must be specified in YAML and it's overall structure is as follows:

‎docs/configuration_file.md‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,13 @@
11
# Configuration file reference
22

3+
<!-- toc -->
4+
5+
* [Top level options](#top-level-options)
6+
* [Diagram options](#diagram-options)
7+
* [Example complete config](#example-complete-config)
8+
9+
<!-- tocstop -->
10+
311
## Top level options
412
* `compilation_database_dir` - path to the directory containing `compile_commands.json`
513
* `output_directory` - path to the directory where PlantUML diagrams will be generated

‎docs/diagram_filters.md‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,17 @@
11
# Diagram filters
22

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

‎docs/doxygen_integration.md‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,11 @@
11
# Doxygen integration
22

3+
<!-- toc -->
4+
5+
6+
7+
<!-- tocstop -->
8+
39
`clang-uml` diagrams can be easily added to the Doxygen documentation using the image tag, however
410
[Doxygen](https://www.doxygen.nl/index.html) does not support the `clang-uml` specific commands.
511

‎docs/include_diagrams.md‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,11 @@
11
# Generating include diagrams
22

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

0 commit comments

Comments
 (0)