### Install MkDoxy from Source Source: https://github.com/jakubandrysek/mkdoxy/blob/main/README.md Install the MkDoxy plugin directly from its GitHub repository using pip. ```bash pip install git+https://github.com/JakubAndrysek/MkDoxy.git ``` -------------------------------- ### Install MkDoxy using pip Source: https://github.com/jakubandrysek/mkdoxy/blob/main/README.md Install the MkDoxy plugin using pip from PyPI. This is the standard installation method. ```bash pip install mkdoxy ``` -------------------------------- ### Install MkDoxy Development Version Source: https://github.com/jakubandrysek/mkdoxy/blob/main/README.md Install the development version of MkDoxy, including all dependencies, using pip. ```bash python -m pip install mkdoxy ".[dev]" ``` -------------------------------- ### MkDocs Configuration with MkDoxy Source: https://github.com/jakubandrysek/mkdoxy/blob/main/README.md Configure the MkDoxy plugin within your mkdocs.yml file. This example shows basic project setup with source directories and Doxygen configuration. ```yaml site_name: "My MkDoxy documentation" theme: name: material plugins: - search - mkdoxy: projects: myProjectCpp: # name of project must be alphanumeric + numbers (without spaces) src-dirs: path/to/src/project1 # path to source code (support multiple paths separated by space) => INPUT full-doc: True # if you want to generate full documentation doxy-cfg: # standard doxygen configuration (key: value) FILE_PATTERNS: "*.cpp *.h*" # specify file patterns to filter out RECURSIVE: True # recursive search in source directories ``` -------------------------------- ### Doxy Tag Structure Example Source: https://github.com/jakubandrysek/mkdoxy/blob/main/docs/snippets/index.md Illustrates the basic structure of a :::doxy tag, including the keyword, project name, tag name, and parameters. ```yaml ::: doxy.. : : ``` -------------------------------- ### Configure Multiple Projects in MkDoxy Source: https://github.com/jakubandrysek/mkdoxy/blob/main/docs/usage/index.md Demonstrates how to configure multiple projects within a single MkDoxy setup. Each project requires its own configuration block under the 'projects' key, including source directories. ```yaml plugins: - mkdoxy: projects: apiProject1: # name of project must be alphanumeric + numbers (without spaces) src-dirs: path/to/src/project1 ... apiProject2: src-dirs: path/to/src/project2 ... predefinedProject3: src-dirs: path/to/src/project3 ... ``` -------------------------------- ### Hints for Parameters in Snippets Source: https://github.com/jakubandrysek/mkdoxy/blob/main/docs/snippets/intelli_sense_and_errors.md Illustrates how MkDoxy provides hints for parameters within snippet configurations, using a specific class name as an example. ```yaml ::: doxy.animal.class.method name: mkdoxy::cache::Cache ``` -------------------------------- ### Doxy Tag Usage Example Source: https://github.com/jakubandrysek/mkdoxy/blob/main/docs/snippets/index.md Provides a concrete example of using the :::doxy tag to reference a specific class method within the mkdoxy project. ```yaml ::: doxy.mkdoxyApi.class.method name: mkdoxy::cache::Cache method: get ``` -------------------------------- ### Generate Code Snippet with Default Start/End Lines Source: https://github.com/jakubandrysek/mkdoxy/blob/main/docs/snippets/source_code.md This example shows how to generate a code snippet using only the file name. The start and end lines will default to the entire file content if not specified. ```yaml ::: doxy.animal.code file: cat.h ``` -------------------------------- ### Namespace List Tag Result Example Source: https://github.com/jakubandrysek/mkdoxy/blob/main/docs/snippets/namespaces.md This shows an example of the output generated by the namespace list tag, with a specified indentation level. ```text indent_level: 4 ``` -------------------------------- ### Function Documentation Error Example Source: https://github.com/jakubandrysek/mkdoxy/blob/main/docs/snippets/functions.md This snippet shows an example of an error message when using the `::: doxy..function` tag with an invalid function name. ```yaml ::: doxy.animal.function name: mEin ``` -------------------------------- ### Override Default Doxygen Configuration in MkDoxy Source: https://github.com/jakubandrysek/mkdoxy/blob/main/docs/usage/index.md This example demonstrates how to override the default Doxygen configuration for a specific project. It includes custom settings for file patterns, recursive search, and other Doxygen options. ```yaml plugins: - mkdoxy: projects: pythonProject: src-dirs: path/to/src/pythonProject full-doc: True doxy-cfg: FILE_PATTERNS: "*.py" EXAMPLE_PATH: "" RECURSIVE: True OPTIMIZE_OUTPUT_JAVA: True JAVADOC_AUTOBRIEF: True EXTRACT_ALL: True ... ``` -------------------------------- ### Namespaced Function Documentation Error Example Source: https://github.com/jakubandrysek/mkdoxy/blob/main/docs/snippets/functions.md This snippet demonstrates an error message when using the `::: doxy..namespace.function` tag with a non-existent function in the specified namespace. ```yaml ::: doxy.animal.namespace.function namespace: example name: void no_function() ``` -------------------------------- ### Generate Code Snippet with Start and End Lines Source: https://github.com/jakubandrysek/mkdoxy/blob/main/docs/snippets/source_code.md Use this tag to extract a specific range of lines from a file. Specify the file name and the start and end line numbers for the desired snippet. ```yaml ::: doxy.animal.code file: bird.h start: 4 end: 20 ``` -------------------------------- ### Generate Full Class Documentation Source: https://github.com/jakubandrysek/mkdoxy/blob/main/docs/snippets/classes.md Use the `::: doxy..class` tag to generate documentation for an entire class. Specify the class name using the `name` parameter. ```yaml ::: doxy.animal.class name: example::Bird ``` ```yaml ::: doxy.animal.class name: example::Bird indent_level: 4 ``` -------------------------------- ### List All Project Files Source: https://github.com/jakubandrysek/mkdoxy/blob/main/docs/snippets/files.md Use this tag to generate a list of all files in the project. No parameters are required. ```yaml ::: doxy.animal.file.list ``` -------------------------------- ### Basic MkDoxy Configuration Source: https://github.com/jakubandrysek/mkdoxy/blob/main/docs/usage/index.md This is a basic configuration for MkDoxy, defining the site name, theme, and enabling the search plugin. It also includes a project named 'myProjectCpp' with specified source directories and Doxygen settings. ```yaml site_name: "My documentation" theme: name: material plugins: - search - mkdoxy: projects: myProjectCpp: # name of project must be alphanumeric + numbers (without spaces) src-dirs: path/to/src/project1 # path to source code (support multiple paths separated by space) => INPUT full-doc: True # if you want to generate full documentation doxy-cfg: # standard doxygen configuration (key: value) FILE_PATTERNS: "*.cpp *.h*" # specify file patterns to filter out RECURSIVE: True # recursive search in source directories ``` -------------------------------- ### Advanced MkDocs Configuration with Multiple Projects Source: https://github.com/jakubandrysek/mkdoxy/blob/main/docs/usage/index.md Configure multiple projects with different settings, including source directories, documentation generation options, and custom Doxygen configurations. The `template-dir` option allows for custom templates. ```yaml plugins: - mkdoxy: projects: apiProject1: # name of project must be alphanumeric + numbers (without spaces) src-dirs: path/to/src/project1 full-doc: True doxy-cfg: FILE_PATTERNS: "*.cpp *.h*" EXAMPLE_PATH: examples RECURSIVE: True apiProject2: src-dirs: path/to/src/project2 full-doc: True template-dir: path/to/userDefined/templates # optional (default is mkdoxy/templates) - custom template will replace default template # Example of custom template: https://mkdoxy-demo.kubaandrysek.cz/esp/annotated/ doxy-cfg: FILE_PATTERNS: "*.py" EXAMPLE_PATH: "" RECURSIVE: True OPTIMIZE_OUTPUT_JAVA: True JAVADOC_AUTOBRIEF: True EXTRACT_ALL: True predefinedProject3: src-dirs: path/to/src/project3 full-doc: False doxy-cfg: PREDEFINED: __cplusplus # example there: https://github.com/kuba2k2/libretuya/blob/master/mkdocs.yml CASE_SENSE_NAMES: NO ... nav: - Home: 'index.md' - API: - Project 1: - 'Links': 'apiProject1/links.md' - 'Classes': - 'Class List': 'apiProject1/annotated.md' - 'Class Index': 'apiProject1/classes.md' - 'Class Hierarchy': 'apiProject1/hierarchy.md' - 'Class Members': 'apiProject1/class_members.md' - 'Class Member Functions': 'apiProject1/class_member_functions.md' - 'Class Member Variables': 'apiProject1/class_member_variables.md' - 'Class Member Typedefs': 'apiProject1/class_member_typedefs.md' - 'Class Member Enumerations': 'apiProject1/class_member_enums.md' - 'Namespaces': - 'Namespace List': 'apiProject1/namespaces.md' - 'Namespace Members': 'apiProject1/namespace_members.md' - 'Namespace Member Functions': 'apiProject1/namespace_member_functions.md' - 'Namespace Member Variables': 'apiProject1/namespace_member_variables.md' - 'Namespace Member Typedefs': 'apiProject1/namespace_member_typedefs.md' - 'Namespace Member Enumerations': 'apiProject1/namespace_member_enums.md' - 'Functions': 'apiProject1/functions.md' - 'Variables': 'apiProject1/variables.md' - 'Macros': 'apiProject1/macros.md' - 'Files': 'apiProject1/files.md' - Project 2: ... use_directory_urls: true # (optional) for better links without .html extension ``` -------------------------------- ### Generate Full Function Documentation Source: https://github.com/jakubandrysek/mkdoxy/blob/main/docs/snippets/functions.md Use the `::: doxy..function` tag to generate documentation for a specific function. Provide the function's full signature as the `name` parameter. ```yaml ::: doxy.animal.function name: int main(int argc, char const *argv[]) ``` -------------------------------- ### Generate List of All Classes Source: https://github.com/jakubandrysek/mkdoxy/blob/main/docs/snippets/classes.md Use the `::: doxy..class.list` tag to generate a list of all classes within the project. This tag requires no parameters. ```yaml ::: doxy.animal.class.list ``` ```yaml ::: doxy.animal.class.list indent_level: 4 ``` -------------------------------- ### Parameter Hints Snippet Result Source: https://github.com/jakubandrysek/mkdoxy/blob/main/docs/snippets/intelli_sense_and_errors.md Displays the rendered output of a snippet demonstrating parameter hints, showing the provided class name and indentation level. ```yaml name: mkdoxy::cache::Cache indent_level: 4 ``` -------------------------------- ### Markdown Links Source: https://github.com/jakubandrysek/mkdoxy/blob/main/demo-projects/animal/markdown-demo.md Demonstrates various link styles: inline with and without titles, reference-style, relative references, and automatic URL detection. Shows how to define reference links. ```markdown [I'm an inline-style link](https://www.google.com) [I'm an inline-style link with title](https://www.google.com "Google's Homepage") [I'm a reference-style link][Arbitrary case-insensitive reference text] [I'm a relative reference to a repository file](../blob/master/LICENSE) [You can use numbers for reference-style link definitions][1] Or leave it empty and use the [link text itself]. URLs and URLs in angle brackets will automatically get turned into links. http://www.example.com or and sometimes example.com (but not on Github, for example). Some text to show that the reference links can follow later. [arbitrary case-insensitive reference text]: https://www.mozilla.org [1]: http://slashdot.org [link text itself]: http://www.reddit.com ``` -------------------------------- ### Markdown Headers Source: https://github.com/jakubandrysek/mkdoxy/blob/main/demo-projects/animal/markdown-demo.md Demonstrates H1 through H6 headers using hash symbols and alternative underline styles for H1 and H2. ```markdown # H1 ## H2 ### H3 #### H4 ##### H5 ###### H6 Alternatively, for H1 and H2, an underline-ish style: Alt-H1 ====== Alt-H2 ------ ``` -------------------------------- ### Generate Specific Class Method Documentation Source: https://github.com/jakubandrysek/mkdoxy/blob/main/docs/snippets/classes.md Use the `::: doxy..class.method` tag to document a specific method within a class. Provide both the class name (`name`) and the method signature (`method`). ```yaml ::: doxy.animal.class.method name: example::Bird method: void make_sound() ``` ```yaml ::: doxy.animal.class.method name: example::Bird method: void make_sound() indent_level: 4 ``` -------------------------------- ### Basic doxy Tag Usage Source: https://github.com/jakubandrysek/mkdoxy/blob/main/docs/snippets/intelli_sense_and_errors.md Demonstrates the basic usage of the 'doxy' tag. This tag is used to display all possible tags and their parameters. ```yaml ::: doxy ``` -------------------------------- ### Generate Namespaced Function Documentation Source: https://github.com/jakubandrysek/mkdoxy/blob/main/docs/snippets/functions.md Use the `::: doxy..namespace.function` tag to generate documentation for functions within a specific namespace. Provide both the namespace and function name. ```yaml ::: doxy.animal.namespace.function namespace: example name: void some_namespace_function(Animal* animal) ``` -------------------------------- ### Configure Custom Doxygen Binary Path Source: https://github.com/jakubandrysek/mkdoxy/blob/main/docs/usage/advanced.md Specify a custom path to the Doxygen binary. If the provided path is invalid, a DoxygenBinPathNotValid exception will be raised. ```yaml plugins: - mkdoxy: doxygen-bin-path: /path/to/doxygen ... ``` -------------------------------- ### Configure Custom Doxygen Configuration File Source: https://github.com/jakubandrysek/mkdoxy/blob/main/docs/usage/index.md Specify a custom Doxygen configuration file using the `doxy-cfg-file` option in the plugin configuration. This path is relative to the `mkdocs.yml` file. ```yaml plugins: - mkdoxy: projects: myProjectCpp: src-dirs: ... doxy-cfg-file: path/to/Doxyfile # relative path to the Doxygen configuration file (relative to the mkdocs.yml file) doxy-cfg: # standard doxygen configuration (key: value) FILE_PATTERNS: ... # other configuration options - merge (this will override the configuration from the Doxyfile) ``` -------------------------------- ### Configure Custom Jinja Templates in MkDoxy Source: https://github.com/jakubandrysek/mkdoxy/blob/main/docs/usage/index.md Shows how to specify a custom template directory for MkDoxy. This allows you to override default Jinja templates and customize the appearance of your generated documentation. ```yaml plugins: - mkdoxy: projects: projectWithCustomTemplate: src-dirs: path/to/src/project1 template-dir: path/to/userDefined/templates # optional (default is mkdoxy/templates) - custom template will replace default template ``` -------------------------------- ### Namespace List Tag Usage Source: https://github.com/jakubandrysek/mkdoxy/blob/main/docs/snippets/namespaces.md Use this tag to generate a list of all namespaces in the project. The output will be indented. ```yaml ::: doxy.animal.namespace.list ``` -------------------------------- ### Generate Class Hierarchy Diagram Source: https://github.com/jakubandrysek/mkdoxy/blob/main/docs/snippets/classes.md Use the `::: doxy..class.hierarchy` tag to generate a visual diagram of the class hierarchy. This tag requires no parameters. ```yaml ::: doxy.animal.class.hierarchy ``` ```yaml ::: doxy.animal.class.hierarchy indent_level: 4 ``` -------------------------------- ### Markdown Emphasis Source: https://github.com/jakubandrysek/mkdoxy/blob/main/demo-projects/animal/markdown-demo.md Shows how to apply italics using asterisks or underscores, bold using double asterisks or underscores, combined emphasis, and strikethrough using double tildes. ```markdown Emphasis, aka italics, with *asterisks* or _underscores_. Strong emphasis, aka bold, with **asterisks** or __underscores__. Combined emphasis with **asterisks and _underscores_**. Strikethrough uses two tildes. ~~Scratch this.~~ ``` -------------------------------- ### Default Doxygen Configuration for MkDoxy Source: https://github.com/jakubandrysek/mkdoxy/blob/main/docs/usage/index.md This Python snippet outlines the default Doxygen configuration used by MkDoxy. It includes essential settings for input/output paths, encoding, XML generation, and recursive searching. ```python "INPUT": self.doxygenSource, # path to source code "OUTPUT_DIRECTORY": self.tempDoxyFolder, # path to temporary folder "DOXYFILE_ENCODING": "UTF-8", # encoding of doxygen configuration file "GENERATE_XML": "YES", # generate XML files (required by mkdoxy) "RECURSIVE": "YES", # recursive search for source files "SHOW_NAMESPACES": "YES", # show namespaces in documentation "GENERATE_HTML": "NO", # do not generate HTML files (mkdoxy generates documentation from XML files) "GENERATE_LATEX": "NO" # do not generate LaTeX files ``` -------------------------------- ### Markdown Lists Source: https://github.com/jakubandrysek/mkdoxy/blob/main/demo-projects/animal/markdown-demo.md Illustrates ordered and unordered lists, including nested sub-lists and indented paragraphs within list items. Also shows how to create line breaks without new paragraphs. ```markdown 1. First ordered list item 2. Another item * Unordered sub-list. 1. Actual numbers don't matter, just that it's a number 1. Ordered sub-list 4. And another item. You can have properly indented paragraphs within list items. Notice the blank line above, and the leading spaces (at least one, but we'll use three here to also align the raw Markdown). To have a line break without a paragraph, you will need to use two trailing spaces. Note that this line is separate, but within the same paragraph. (This is contrary to the typical GFM line break behaviour, where trailing spaces are not required.) * Unordered list can use asterisks - Or minuses + Or pluses ``` -------------------------------- ### Handling Incorrect Arguments in Snippets Source: https://github.com/jakubandrysek/mkdoxy/blob/main/docs/snippets/intelli_sense_and_errors.md Demonstrates how MkDoxy handles snippets configured with incorrect arguments, showing an error message from mkdoxyApi. ```yaml ::: doxy.animal.class.method name: cat ``` -------------------------------- ### Markdown Images Source: https://github.com/jakubandrysek/mkdoxy/blob/main/demo-projects/animal/markdown-demo.md Shows how to embed images using inline and reference styles, including alt text and title attributes for hover effects. ```markdown Here's our logo (hover to see the title text): Inline-style: ![alt text](https://github.com/adam-p/markdown-here/raw/master/src/common/images/icon48.png "Logo Title Text 1") Reference-style: ![alt text][logo] [logo]: https://github.com/adam-p/markdown-here/raw/master/src/common/images/icon48.png "Logo Title Text 2" ``` -------------------------------- ### Error Handling for Incorrect Snippet Configuration Source: https://github.com/jakubandrysek/mkdoxy/blob/main/docs/snippets/intelli_sense_and_errors.md Illustrates an error message displayed by MkDoxy when a snippet is configured incorrectly. It provides a hint on how to fix the issue. ```yaml ::: doxy.animal ``` -------------------------------- ### Markdown Blockquotes Source: https://github.com/jakubandrysek/mkdoxy/blob/main/demo-projects/animal/markdown-demo.md Use the greater-than symbol (>) at the beginning of lines to create blockquotes. Multiple lines form a single quote, and Markdown formatting can be used within them. ```markdown > Blockquotes are very handy in email to emulate reply text. > This line is part of the same quote. Quote break. > This is a very long line that will still be quoted properly when it wraps. Oh boy let's keep writing to make sure this is long enough to actually wrap for everyone. Oh, you can *put* **Markdown** into a blockquote. ``` -------------------------------- ### Disable MkDoxy Plugin Conditionally Source: https://github.com/jakubandrysek/mkdoxy/blob/main/docs/usage/advanced.md Disable the MkDoxy plugin based on an environment variable. Useful for speeding up local builds. The plugin is disabled if ENABLE_MKDOXY is not set or is 'False'. ```yaml plugins: - mkdoxy: enabled: !ENV [ENABLE_MKDOXY, True] ... ``` ```bash export ENABLE_MKDOXY=False mkdocs serve ``` -------------------------------- ### Incorrect Arguments Snippet Result Source: https://github.com/jakubandrysek/mkdoxy/blob/main/docs/snippets/intelli_sense_and_errors.md Shows the result of a snippet configured with incorrect arguments, including the name parameter and indentation level. This is the output displayed when an error occurs. ```yaml name: example::Cat indent_level: 4 ``` -------------------------------- ### Inline HTML for Definition Lists Source: https://github.com/jakubandrysek/mkdoxy/blob/main/demo-projects/animal/markdown-demo.md Inline HTML can be used for elements not directly supported by Markdown, such as definition lists. Markdown formatting within HTML tags is generally not rendered. ```html
Definition list
Is something people use sometimes.
Markdown in HTML
Does *not* work **very** well. Use HTML tags.
``` -------------------------------- ### Markdown Table with Alignment Source: https://github.com/jakubandrysek/mkdoxy/blob/main/demo-projects/animal/markdown-demo.md Use colons in the header separator line to control text alignment within table columns. Left, center, and right alignments are supported. ```markdown Colons can be used to align columns. | Tables | Are | Cool | | ------------- |:-------------:| -----:| | col 3 is | right-aligned | $1600 | | col 2 is | centered | $12 | | zebra stripes | are neat | $1 | There must be at least 3 dashes separating each header cell. The outer pipes (|) are optional, and you don't need to make the raw Markdown line up prettily. You can also use inline Markdown. Markdown | Less | Pretty --- | --- | --- *Still* | `renders` | **nicely** 1 | 2 | 3 ``` === COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.