Update docs, upgrade version, improve makefile

Makefile

@@ -1,7 +1,6 @@
-.PHONY: package release
-
-all: package
+.PHONY: package release release-test clean reviewCode docs-serve docs-build
 
+# Packaging
 package:
 	rm -f dist/*
 	python3 setup.py sdist bdist_wheel
@@ -18,5 +17,17 @@ release-test: package
 clean:
 	rm -rf dist build
 
+
+# Testing
 reviewCode:
-	sourcery review mkdoxy --in-place
+	sourcery review mkdoxy --in-place
+
+install-dev:
+	python3.11 -m pip install --force --editable .
+
+# Documentation
+docs-serve:
+	mkdocs serve
+
+docs-build: # results in site directory
+	mkdocs build

README.md

@@ -1,14 +1,19 @@
 # MkDoxy
 
-## MkDoxy → MkDocs + Doxygen. Easy documentation generator with code snippets.
+## MkDoxy → MkDocs + Doxygen = easy documentation generator with code snippets
 
 
 <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">
 </p>
 
-### [MkDoxy](https://github.com/JakubAndrysek/MkDoxy) is based on  [matusnovak/doxybook](https://matusnovak.github.io/doxybook)
+
+> **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://matusnovak.github.io/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.
@@ -21,22 +26,10 @@ Next usage is by snippets inside documentation markdown.
 
 ## Requirements
 
-### Tools
-
-- python 3.6 or newer → `sudo apt install python3`
+- python 3.8 or newer → `sudo apt install python3`
 - Pip → `sudo apt install python3-pip`
-- Git → `sudo apt install git`
 - Doxygen → `sudo apt install doxygen`
-
-### Pip
-
-- Jinja2 → `pip install jinja2`
-- Mkdocs → `pip install mkdocs`
-- ruamel.yaml → `pip install ruamel.yaml`
-
-### Optional:
-
-- mkdocs-material → `pip install mkdocs-material`
+- Git → `sudo apt install git` (optional)
 
 ## Installation
 
@@ -46,12 +39,13 @@ Next usage is by snippets inside documentation markdown.
 pip install mkdoxy
 ```
 
-**Or Install manually:**
+**Or installation from source:**
 
 ```bash
 git clone https://github.com/JakubAndrysek/MkDoxy.git
 cd mkdoxy
-python setup.py install
+python setup.py install # for normal usage
+pip install -e . # for development (source code changes are applied immediately)
 ```
 
 ## Example usage
@@ -105,7 +99,7 @@ plugins:
             EXAMPLE_PATH: examples
             RECURSIVE: True
         apiProject2:
-          src-dirs: sw/python-wrapper/
+          src-dirs: path/to/src/project2
           full-doc: True
           doxy-cfg:
             FILE_PATTERNS: "*.py"
@@ -116,7 +110,7 @@ plugins:
             EXTRACT_ALL: True
 ...
 nav:
-  - 'Home': 'index.md'
+  - Home: 'index.md'
   - API:
       - Project 1:
           - 'Links': 'apiProject1/links.md'
@@ -142,8 +136,16 @@ nav:
           - 'Files': 'apiProject1/files.md'
       - Project 2:
 ...
+
+use_directory_urls: true # (optional) for better links without .html extension
 ```
 
+## 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. `use_directory_urls: false` doesn't work with Mkdoxy. 
+   - **Not fixed yet**
+
 
 ## License
 

setup.py

@@ -4,23 +4,24 @@ def readme():
     with open('README.md') as f:
         return f.read()
 
+def requirements():
+    with open('requirements.txt') as f:
+        return f.read().splitlines()
+
+# https://pypi.org/project/mkdoxy/
 setup(
     name='mkdoxy',
-    version='1.0.2',
-    description='MkDoxy → MkDocs + Doxygen. Easy documentation generator with code snippets.',
+    version='1.0.3',
+    description='MkDoxy → MkDocs + Doxygen = easy documentation generator with code snippets',
     long_description=readme(),
     long_description_content_type='text/markdown',
-    keywords=['python', 'open-source', 'documentation', 'mkdocs', 'doxygen', 'multilanguage'],
+    keywords=['mkdoxy', 'python', 'open-source', 'documentation', 'mkdocs', 'doxygen', 'multilanguage', 'code-snippets', 'code', 'snippets', 'documentation-generator'],
     url='https://github.com/JakubAndrysek/mkdoxy',
     author='Jakub Andrýsek',
     author_email='[email protected]',
     license='MIT',
     python_requires='>=3.8',
-    install_requires=[
-        'mkdocs',
-        'Jinja2',
-        'ruamel.yaml',
-    ],
+    install_requires=requirements(),
     classifiers=[
         'License :: OSI Approved :: MIT License',
         'Programming Language :: Python :: 3.8',