diff --git a/Makefile b/Makefile index c83f3e4d..0548e318 100644 --- a/Makefile +++ b/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 diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 00000000..7b78c4f5 --- /dev/null +++ b/docs/Makefile @@ -0,0 +1,37 @@ +# docs/Makefile +# +# Copyright (c) 2021-2023 Bartek Kryza +# +# 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 + diff --git a/docs/README.md b/docs/README.md index fcfddc50..9f6a366b 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,6 +1,5 @@ # Documentation - * [Quick start](./quick_start.md) * [Installation](./installation.md) * Generating diagrams diff --git a/docs/class_diagrams.md b/docs/class_diagrams.md index 23b53f74..99bca57e 100644 --- a/docs/class_diagrams.md +++ b/docs/class_diagrams.md @@ -1,5 +1,18 @@ # Generating class diagrams + + +* [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) + + + The minimal config required to generate a class diagram is presented below: ```yaml # Path to the directory where `compile_commands.json` can be found diff --git a/docs/comment_decorators.md b/docs/comment_decorators.md index 1216bfa6..783c984e 100644 --- a/docs/comment_decorators.md +++ b/docs/comment_decorators.md @@ -1,5 +1,14 @@ # Comment decorators + + +* [`note`](#note) +* [`skip` and `skiprelationship`](#skip-and-skiprelationship) +* [`composition`, `association` and `aggregation`](#composition-association-and-aggregation) +* [`style`](#style) + + + `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 diff --git a/docs/common_options.md b/docs/common_options.md index 52e46091..d46f6d44 100644 --- a/docs/common_options.md +++ b/docs/common_options.md @@ -1,5 +1,14 @@ # Common diagram generation options + + +* [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) + + + ## 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: diff --git a/docs/configuration_file.md b/docs/configuration_file.md index 76a777c2..26397e64 100644 --- a/docs/configuration_file.md +++ b/docs/configuration_file.md @@ -1,5 +1,13 @@ # Configuration file reference + + +* [Top level options](#top-level-options) + * [Diagram options](#diagram-options) +* [Example complete config](#example-complete-config) + + + ## 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 diff --git a/docs/diagram_filters.md b/docs/diagram_filters.md index 946217cf..39c7d88d 100644 --- a/docs/diagram_filters.md +++ b/docs/diagram_filters.md @@ -1,5 +1,17 @@ # Diagram filters + + +* [`namespaces`](#namespaces) +* [`elements`](#elements) +* [`context`](#context) +* [`relationships`](#relationships) +* [`subclasses`](#subclasses) +* [`specializations`](#specializations) +* [`dependants` and `dependencies`](#dependants-and-dependencies) + + + 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. diff --git a/docs/doxygen_integration.md b/docs/doxygen_integration.md index 119096c3..285b3708 100644 --- a/docs/doxygen_integration.md +++ b/docs/doxygen_integration.md @@ -1,5 +1,11 @@ # Doxygen integration + + + + + + `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. diff --git a/docs/include_diagrams.md b/docs/include_diagrams.md index 7e92eda9..b8b6c087 100644 --- a/docs/include_diagrams.md +++ b/docs/include_diagrams.md @@ -1,5 +1,11 @@ # Generating include diagrams + + +* [Tracking system headers directly included by projects files](#tracking-system-headers-directly-included-by-projects-files) + + + 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. diff --git a/docs/installation.md b/docs/installation.md index b6b005bd..5f41f309 100644 --- a/docs/installation.md +++ b/docs/installation.md @@ -1,5 +1,19 @@ # Installation + + +* [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) + + + ### Distribution packages #### Ubuntu diff --git a/docs/interactive_svg_diagrams.md b/docs/interactive_svg_diagrams.md index 92a09d13..d59de82b 100644 --- a/docs/interactive_svg_diagrams.md +++ b/docs/interactive_svg_diagrams.md @@ -1,5 +1,11 @@ # Interactive SVG diagrams + + + + + + `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. diff --git a/docs/jinja_templates.md b/docs/jinja_templates.md index 168a0c9d..9644e253 100644 --- a/docs/jinja_templates.md +++ b/docs/jinja_templates.md @@ -1,4 +1,13 @@ # Template engine + + + +* [Accessing comment content](#accessing-comment-content) + * [`plain` comment parser](#plain-comment-parser) + * [`clang` comment parser](#clang-comment-parser) + + + `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. diff --git a/docs/package_diagrams.md b/docs/package_diagrams.md index 03182010..bf900a22 100644 --- a/docs/package_diagrams.md +++ b/docs/package_diagrams.md @@ -1,5 +1,11 @@ # Generating package diagrams + + + + + + 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. diff --git a/docs/quick_start.md b/docs/quick_start.md index 23054f05..268c09ad 100644 --- a/docs/quick_start.md +++ b/docs/quick_start.md @@ -1,5 +1,11 @@ # Quick start + + + + + + To add an initial class diagram to your project, follow these steps: 1. Enter your projects top level directory and run: diff --git a/docs/sequence_diagrams.md b/docs/sequence_diagrams.md index 46070fde..b7fbd723 100644 --- a/docs/sequence_diagrams.md +++ b/docs/sequence_diagrams.md @@ -1,5 +1,15 @@ # Generating sequence diagrams + + +* [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) + + + The minimal config required to generate a sequence diagram is presented below: ```yaml # Path to the directory where `compile_commands.json` can be found diff --git a/docs/test_cases.md b/docs/test_cases.md index d736eb99..a92d6d2e 100644 --- a/docs/test_cases.md +++ b/docs/test_cases.md @@ -1,4 +1,15 @@ # Test cases index + + + +* [Class diagrams](#class-diagrams) +* [Sequence diagrams](#sequence-diagrams) +* [Package diagrams](#package-diagrams) +* [Include diagrams](#include-diagrams) +* [Configuration diagrams](#configuration-diagrams) + + + ## Class diagrams * [t00002](./test_cases/t00002.md) - Basic class inheritance * [t00003](./test_cases/t00003.md) - Class field and methods diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md index cb624294..bc5ede87 100644 --- a/docs/troubleshooting.md +++ b/docs/troubleshooting.md @@ -1,5 +1,17 @@ # Troubleshooting + + +* [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) + + + ## General issues ### Diagram generated with PlantUML is cropped When generating diagrams with PlantUML without specifying an output file format, the default is PNG.