Skip to content

Commit

Permalink
docs(usage): include MrDocs workflow
Browse files Browse the repository at this point in the history
  • Loading branch information
alandefreitas committed Nov 27, 2024
1 parent 555e2c4 commit 0e08458
Showing 1 changed file with 22 additions and 0 deletions.
22 changes: 22 additions & 0 deletions docs/modules/ROOT/pages/usage.adoc
Original file line number Diff line number Diff line change
@@ -1,5 +1,25 @@
= Basic Usage

The diagram below illustrates the workflow of the MrDocs documentation tool.
It shows how inputs are transformed step by step into the final documentation output.
Each component in the diagram represents a distinct type of entity:

- **Inputs**: Provide the initial parameters and settings required to configure and run the tool.
These include the <<config-file,configuration file>> and <<cli,command-line arguments>>.
- **Processes**: Represent intermediary outputs or data generated during the workflow.
- **Outputs**: The final product, in this case, the generated documentation.
include::partial$workflow.adoc[]

In summary:

* Begin by specifying the <<config-file,configuration file>> and <<cli,command-line arguments>> to set up the options. The configuration options affect all processes.
* The configuration options define a <<compilation-database, Compilation Database>>. All symbols are extracted with Clang to generate a unified corpus of symbols with their corresponding xref:page$commands.adoc[documentation].
* Finally, This corpus is then fed to a xref:page$generators.adoc[Generator] that produces the desired documentation.
For more details on each component, refer to the corresponding sections of this guide.

[#config-file]
== MrDocs configuration file

The `mrdocs.yml` configuration file contains information about the project.
Expand Down Expand Up @@ -30,6 +50,7 @@ The most important information is the `source-root` option, which determines the

The list of all available options can be found in the xref:config-file.adoc[] page.

[#cli]
== MrDocs invocation

NOTE: For consistency, these instructions assume you have the `mrdocs` executable in PATH.
Expand Down Expand Up @@ -59,6 +80,7 @@ mrdocs path/to/mrdocs.yml --output=../docs/reference

NOTE: Except for the path to the `mrdocs.yml` file, all other relative paths are made absolute relative to the `mrdocs.yml` file.

[#compilation-database]
=== Compilation databases

One way to simplify the documentation generation process is by using a `compile_commands.json` file generated by CMake to determine the source files to process and their compile options.
Expand Down

0 comments on commit 0e08458

Please sign in to comment.