address review comments

CONTRIBUTING.md

@@ -34,6 +34,8 @@ and smooth out the experience for all involved. The community looks forward to y
       - [Run the linter](#run-the-linter)
       - [Run the tests](#run-the-tests)
     - [Improving The Documentation](#improving-the-documentation)
+      - [Python API docs](#python-api-docs)
+      - [Documentation pages](#documentation-pages)
 
 
 ## Code of Conduct
@@ -103,7 +105,7 @@ to existing ones. Following these guidelines will help maintainers and the commu
 ### Before Submitting an Enhancement
 
 - Make sure that you are using the latest version.
-- Read the [documentation]() carefully and find out if the functionality is already covered, maybe by an individual configuration.
+- Read the [documentation](https://docs.haystack.deepset.ai/v2.0/docs/intro) carefully and find out if the functionality is already covered, maybe by an individual configuration.
 - Perform a [search](/issues) to see if the enhancement has already been suggested. If it has, add a comment to the existing issue instead of opening a new one.
 - Find out whether your idea fits with the scope and aims of the project. It's up to you to make a strong case to convince the project's developers of the merits of this feature. Keep in mind that we want features that will be useful to the majority of our users and not just a small subset. If you're just targeting a minority of users, consider writing and distributing the integration on your own.
 
@@ -237,17 +239,31 @@ $ hatch run test -m"not integration"
 
 ### Improving The Documentation
 
-There are two types of documentation for this project:
+There are two types of documentation for this project: Python API docs, and Documentation pages
 
-1. Python API docs, and
-2. Documentation pages
+#### Python API docs
 
 The Python API docs detail the source code: classes, functions, and parameters that every integration implements.
 This type of documentation is extracted from the source code itself, and contributors should pay attention when they
 change the code to also change relevant comments and docstrings. This type of documentation is mostly useful to
 developers, but it can be handy for users at times. You can browse it on the dedicated section in the
 [documentation website](https://docs.haystack.deepset.ai/v2.0/reference/integrations-chroma).
 
+We use `pydoc-markdown` to convert docstrings into properly formatted Markdown files, and while the CI takes care of
+generating and publishing the updated documentation at every merge on the `main` branch, you can generate the docs
+locally using Hatch. From an integration folder:
+
+```console
+$ hatch run docs
+```
+
+If you see a warning referring to a missing `README_API_KEY` env var, that's expected.
+
+If you want to customise the conversion process, the `pydoc-markdown` config files are stored in a `pydoc/` folder
+for each integration.
+
+#### Documentation pages
+
 Documentation pages explain what an integration accomplishes, how to use it, and how to configure it. This
 type of documentation mostly targets end-users, and contributors are welcome to make changes and keep it up-to-date.
 You can contribute changes to the documentation using the "Suggest Edits" button in the top-right corner of each page.