Merge pull request #50 from JakubAndrysek/new-templates

New templates + add Documentation

.github/workflows/deploy-web.yaml

@@ -20,6 +20,6 @@ jobs:
           path: .cache
       - run: pip install -r requirements.txt
       - run: pip install mkdocs-material # not in requirements.txt because it's not needed for the build
-      - run: pip install mkdoxy
+      - run: pip install . # install the plugin itself (mkdoxy)
       - run: sudo apt-get install doxygen
       - run: mkdocs gh-deploy --force

.github/workflows/mkdoxy-build-test.yaml → .github/workflows/mkdoxy-test-demos.yaml

@@ -1,15 +1,14 @@
-name: MkDoxy build all supported Python versions
+name: MkDoxy test build demos with all supported python versions
 
 on: [push]
 
 jobs:
   build:
-
     runs-on: ubuntu-latest
     strategy:
       # You can use PyPy versions in python-version.
       matrix:
-        python-version: ["3.8", "3.9", "3.10", "3.11"]
+        python-version: ["3.9", "3.10", "3.11"]
 
     steps:
       - uses: actions/checkout@v3
@@ -20,16 +19,16 @@ jobs:
       # You can test your matrix by printing the current Python version
       - name: Display Python version
         run: python -c "import sys; print(sys.version)"
-      - name: Clone test repo
-        run: git clone https://github.com/JakubAndrysek/MkDoxy-demo.git demo
-      - name: Change directory
-        run: cd demo
       - name: Install dependencies
         run: |
           python -m pip install --upgrade pip
           pip install -r requirements.txt
           pip install mkdocs-material
-          pip install mkdoxy
+          pip install .
           sudo apt-get install doxygen
+      - name: Clone test repo
+        run: git clone https://github.com/JakubAndrysek/MkDoxy-demo.git demo
+      - name: Change directory
+        run: cd demo
       - name: Build docs
-        run: mkdocs build --clean --strict --verbose
+        run: mkdocs build --clean --verbose

.github/workflows/mkdoxy-test-repo.yaml

@@ -0,0 +1,30 @@
+name: MkDoxy test build this doc with all supported python versions
+
+on: [push]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    strategy:
+      # You can use PyPy versions in python-version.
+      matrix:
+        python-version: ["3.9", "3.10", "3.11"]
+
+    steps:
+      - uses: actions/checkout@v3
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v4
+        with:
+          python-version: ${{ matrix.python-version }}
+      # You can test your matrix by printing the current Python version
+      - name: Display Python version
+        run: python -c "import sys; print(sys.version)"
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -r requirements.txt
+          pip install mkdocs-material
+          pip install .
+          sudo apt-get install doxygen
+      - name: Build docs
+        run: mkdocs build --clean --verbose

.gitignore

@@ -288,4 +288,5 @@ tests/files/.mkdoxy
 .DS_Store
 .mkdoxy/
 templates-custom
-temp/
+temp/
+local/

CHANGELOG.md

@@ -0,0 +1,11 @@
+# Changelog
+All notable changes to this project will be documented in this file.
+
+- **v1.0.0** - 2023-01-24
+    - Initial release
+- **v1.0.3** - 2023-03-21
+    - Fix: Hash function [support subfolders](https://github.com/JakubAndrysek/MkDoxy/pull/29)
+- **v1.0.5** - 2023-04-01
+    - Add support for [custom templates](https://github.com/JakubAndrysek/MkDoxy/pull/39)
+- **v1.0.6** - 2023-04-01
+    - Add support disable plugin [using environment variable](#disabling-the-plugin)

README.md

@@ -1,210 +1,75 @@
 # MkDoxy
 
-## MkDoxy → MkDocs + Doxygen = easy documentation generator with code snippets
-
+**[MkDoxy](https://mkdoxy.kubaandrysek.cz/)** plugin for **[MkDocs](https://www.mkdocs.org/)** generates API documentation based on **[Doxygen](https://www.doxygen.nl)** comments and **[code snippets](/intro)** in your markdown files.
 
 <p align="center">
 <a href="https://hits.seeyoufarm.com"><img src="https://hits.seeyoufarm.com/api/count/incr/badge.svg?url=https%3A%2F%2Fgithub.com%2FJakubAndrysek%2FMkDoxy&count_bg=%2379C83D&title_bg=%23555555&icon=&icon_color=%23E7E7E7&title=hits&edge_flat=true"/></a>
-<img src="https://img.shields.io/github/license/JakubAndrysek/MkDoxy?style=flat-square">
-<img src="https://img.shields.io/github/v/release/JakubAndrysek/MkDoxy?style=flat-square">
-<img src="https://img.shields.io/github/stars/JakubAndrysek/MkDoxy?style=flat-square">
-<img src="https://img.shields.io/github/forks/JakubAndrysek/MkDoxy?style=flat-square">
-<img src="https://img.shields.io/github/issues/JakubAndrysek/MkDoxy?style=flat-square">
-<img src="https://img.shields.io/github/discussions/JakubAndrysek/MkDoxy?style=flat-square">
-<img src="https://static.pepy.tech/personalized-badge/mkdoxy?period=month&units=international_system&left_color=black&right_color=orange&left_text=Downloads">
-
-
+<a href="https://github.com/JakubAndrysek/MkDoxy/blob/main/LICENSE" target="_blank"><img src="https://img.shields.io/github/license/JakubAndrysek/MkDoxy?style=flat-square"></a>
+<a href="https://github.com/JakubAndrysek/MkDoxy/releases" target="_blank"><img src="https://img.shields.io/github/v/release/JakubAndrysek/MkDoxy?style=flat-square"></a>
+<a href="https://github.com/JakubAndrysek/MkDoxy/stargazers" target="_blank"><img src="https://img.shields.io/github/stars/JakubAndrysek/MkDoxy?style=flat-square"></a>
+<a href="https://github.com/JakubAndrysek/MkDoxy/forks" target="_blank"><img src="https://img.shields.io/github/forks/JakubAndrysek/MkDoxy?style=flat-square"></a>
+<a href="https://github.com/JakubAndrysek/MkDoxy/issues" target="_blank"><img src="https://img.shields.io/github/issues/JakubAndrysek/MkDoxy?style=flat-square"></a>
+<a href="https://github.com/JakubAndrysek/MkDoxy/discussions" target="_blank"><img src="https://img.shields.io/github/discussions/JakubAndrysek/MkDoxy?style=flat-square"></a>
+<a href="https://pypistats.org/packages/mkdoxy" target="_blank"><img src="https://static.pepy.tech/personalized-badge/mkdoxy?period=month&units=international_system&left_color=black&right_color=orange&left_text=Downloads"></a>
 </p>
 
-
 > **Warning**
 > **Extension is in development** and few features are not working properly.
-> More information in [Known issues](#known-issues) section and [Issues](https://github.com/JakubAndrysek/MkDoxy/issues) page.
-
-#### [MkDoxy](https://github.com/JakubAndrysek/MkDoxy) is based on  [matusnovak/doxybook](https://github.com/matusnovak/doxybook)
-
-This python tool is extension for MkDocs. Extension will take your programme source code and runs Doxygen.
-Then converts exported XML into markdown and create new folder with full generated documentation.
-Next usage is by snippets inside documentation markdown.
+> More information in [Discussions](https://github.com/JakubAndrysek/MkDoxy/discussions) and [Issues](https://github.com/JakubAndrysek/MkDoxy/issues) pages.
 
-## [Online Demo](https://jakubandrysek.github.io/MkDoxy-demo/) and [Demo Source](https://github.com/JakubAndrysek/MkDoxy-demo)
+---
 
+## [:material-home-edit: Online Demo](https://jakubandrysek.github.io/MkDoxy-demo/) and [:simple-github: Demo source-code ](https://github.com/JakubAndrysek/MkDoxy-demo)
 
-![Basic-implementation](https://github.com/JakubAndrysek/MkDoxy/raw/main/docs/media/Basic-implementation.png)
+---
 
-## Features
-- **Easy to use:** just add `mkdoxy` to your `mkdocs.yml` and config path to your project `src` folder.
-- **Code snippets:** `mkdoxy` supports code snippets in your documentation. Just add `::: <project_name>.<command_name>` to your markdown file and `mkdoxy` will generate code just in the place where you want it. Inspired from [mkdocstrings](https://mkdocstrings.github.io/).
-- **Multiple projects:** `mkdoxy` supports multiple projects. You can add multiple source folders and generate documentation for all of them. For example, you can generate documentation for your C++ project and your Python project like in [this example](https://mkdoxy-demo.kubaandrysek.cz/api/).
-- **Custom API documentation structure** is allowed using Jinja2 templates. You can add your own templates and generate documentation in any structure you want.
+**[Feature List](#feature-list)** - **[Installation](#installation)** - **[Quick start](#quick-start)**
 
-
-
-## Requirements
-
-- python 3.8 or newer → `sudo apt install python3`
-- Pip → `sudo apt install python3-pip`
-- Doxygen → `sudo apt install doxygen`
-- Git → `sudo apt install git` (optional)
+## Feature List
+- **[Easy to use](#quick-start):**: Just add `mkdoxy` to your `mkdocs.yml` and configure the path to your source code.
+- **[Code snippets](./snippets/index.md)**: Generate code snippets in place of your standard Markdown documentation.
+- **[Multiple projects](./usage/index.md#multiple-projects)**: Support for multiple projects in one documentation (e.g. C++ and Python).
+- **[Multiple source directories](./usage/index.md#multiple-source-directories)**: Configure multiple source directories in one project.
+- **[Custom Jinja templates](./usage/index.md#custom-jinja-templates)**: Define custom Jinja templates for rendering Doxygen documentation.
+- **[Custom Doxygen configuration](./usage/index.md#custom-doxygen-configuration)**: Specify custom Doxygen configuration for each project.
 
 ## Installation
-
-**Install using Python Pip: <https://pypi.org/project/MkDoxy/>**
-
+With [pip](https://pypi.org/project/mkdoxy/):
 ```bash
 pip install mkdoxy
 ```
 
-**Or installation from source:**
-
+Install from source - development version:
 ```bash
-git clone https://github.com/JakubAndrysek/MkDoxy.git
-cd mkdoxy
-python setup.py install # for normal usage
-pip install -e . # for development (source code changes are applied immediately)
+pip install git+https://github.com/JakubAndrysek/MkDoxy.git
 ```
 
-## Example usage
-
-Set `[PROJECT]` according to your project names configured in `mkdocs.yml`.
-
-```bash
-
-1. Generate class with name `rb::MotorChangeBuilder`
+## Quick start
 
+`mkdocs.yml`:
 ```yaml
-::: doxy.[PROJECT].Class
-  name: rb::MotorChangeBuilder
-```
+site_name: "My documentation"
 
-2. Generate method `brake (MotorId id, uint16_t brakingPower)` from class with name `rb::MotorChangeBuilderA`
+theme:
+  name: material
 
-```yaml
-::: doxy.[PROJECT].Class.Method
-  name: rb::MotorChangeBuilder
-  method: brake (MotorId id, uint16_t brakingPower)
-```
-
-3. Generate function with name `readUltra (bool async)`
-
-```yaml
-::: doxy.[PROJECT].Function
-  name: readUltra (bool async)
-```
-
-4. Generate code snippet from file `RBCXLeds.cpp`
-
-```yaml
-::: doxy.[PROJECT].Code
-  file: RBCXLeds.cpp
-  start: 21
-  end: 35
-```
-
-## Mkdocs.yml configuration
-
-<details>
-<summary>Click to expand</summary>
-
-```yaml
 plugins:
+  - search
   - 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
+        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
 ```
-</details>
-
-## Known issues
-1. **Doxygen** is not able to parse **Python** code.
-    - **Solution**: Use `OPTIMIZE_OUTPUT_JAVA: True` and `JAVADOC_AUTOBRIEF: True` in `doxy-cfg` section of `mkdocs.yml`.
-2. **Relative links from snippets** are not working properly.
-    - In some cases, relative links are not working properly.
-    - For example link [on test page](https://mkdoxy-demo.kubaandrysek.cz/api/#:~:text=Class%20rb%3A%3AMotorChangeBuilder-,ClassList,-%3E%20rb%20%3E) - `ClassList` under `Class rb::MotorChangeBuilder` is not working.
-
-## Changes
 
-- **v1.0.0** - 2023-01-24
-    - Initial release
-- **v1.0.3** - 2023-03-21
-    - Fix: Hash function [support subfolders](https://github.com/JakubAndrysek/MkDoxy/pull/29)
-- **v1.0.5** - 2023-04-01
-    - Add support for [custom templates](https://github.com/JakubAndrysek/MkDoxy/pull/39)
-- **v1.0.6** - 2023-04-01
-    - Add support disable plugin [using environment variable](#disabling-the-plugin)
+## Do You Enjoy MkDoxy or Does It Save You Time?
+Then definitely consider:
 
-
-## Disabling the plugin
-You can use the `enabled` option to optionally disable this plugin. A possible use case is local development where you might want faster build times.
-
-```yaml
-plugins:
-  - mkdoxy:
-      enabled: !ENV [ENABLE_MKDOXY, True]
-      ...
-```
-
-This will disable the plugin if the `ENABLE_MKDOXY` environment variable is not set or is set to `False`.
-Inspirated by [mkdocs-simple-hooks](https://github.com/aklajnert/mkdocs-simple-hooks)
-
-```bash
-export ENABLE_MKDOXY=False
-mkdocs serve
-```
+- supporting me on GitHub Sponsors: [![](https://img.shields.io/static/v1?label=Sponsor&message=%E2%9D%A4&logo=GitHub&color=%23fe8e86)](https://github.com/sponsors/jakubandrysek)
 
 ## License
 
-This project is licensed under the terms of the [MIT license]([/LICENSE](https://github.com/JakubAndrysek/MkDoxy/blob/main/LICENSE))
+This project is licensed under the terms of the [MIT license](https://github.com/JakubAndrysek/MkDoxy/blob/main/LICENSE)

demo-projects/animal/Readme.md

@@ -0,0 +1,3 @@
+# Source
+
+Code from [doxybook demo](https://github.com/matusnovak/doxybook/tree/master/example/src).