Add mkdocs integration documentation

Author: lukasmasuch

README.md

@@ -24,7 +24,7 @@
   <a href="https://github.com/ml-tooling/lazydocs/releases">Changelog</a>
 </p>
 
-Lazydocs makes it easy to generate beautiful markdown documentation for your Python API (see this [example](./docs)). It provides a simple command-line interface as well as a Python API to get full-fledged API documentation within seconds based on all of the [Google-style docstrings](https://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_google.html) in your code. This markdown documentation can be pushed to Github or integrated into your MkDocs site.
+Lazydocs makes it easy to generate beautiful markdown documentation for your Python API (see this [example](./docs)). It provides a [simple command-line interface](#cli-interface) as well as a [Python API](#programmatic-api) to get full-fledged API documentation within seconds based on all of the [Google-style docstrings](https://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_google.html) in your code. This markdown documentation can be pushed to Github or integrated into your MkDocs site.
 
 ## Highlights
 
@@ -104,9 +104,33 @@ lazydocs --overview-file="README.md" my_package
 
 The API overview will be written as markdown to the specified file with separated lists for all modules, classes, and functions of your project:
 
-### MKDocs Integration
+### MkDocs Integration
 
+<img style="width: 100%" src="./docs/images/mkdocs-integration.png"/>
 
+The markdown documentation generated by lazydocs can be easily integrated into your [mkdocs](https://www.mkdocs.org/) documentation site:
+
+1. Generate the markdown documentation into a subfolder (e.g. `api-docs`) inside your mkdocs documentation. We recommend to use the `overview-file` option and set the source-code URL via `src-base-url`, otherwise the source-code linking would not work:
+
+```bash
+lazydocs \
+    --overview-file="README.md" \
+    --src-base-url="https://github.com/example/my-project/blob/main/" \
+    my_package
+```
+
+2. Install and apply the [awesome-pages mkdocs plugin](https://github.com/lukasgeiter/mkdocs-awesome-pages-plugin). This enables mkdocs to automatically discover and include all markdown files. The alternative would be to manually include all generated markdown files in the navigation section of the `mkdocs.yaml`. In order to use the awesome-pages plugin you need to 1) install the plugin via pip 2) Include it in the plugin section `mkdocs.yaml` and remove the navigation section (needs to be handled with `.pages` files).
+
+3. Create a `.pages` file within the api-docs subfolder (e.g. `api-docs`) with the following content:
+
+    ```yaml
+    title: API Reference
+    nav:
+       - Overview: README.md
+       - ...
+    ```
+
+Once you run or deploy your mkdocs documentation, you will see the API Reference section with all the API markdown documentation.
 
 ### Docstyle Validation