Update the api reference docs

docs/contributing/guides/docstrings-and-reference.md → docs/contributing/guides/api-reference.md

@@ -2,7 +2,14 @@
 
     This page is still being written. The content below (if any) may change.
 
-# Docstrings and API reference
+# API reference
+
+???+ abstract
+
+This page contains the guide on documenting the code that will appear in the API reference section of this
+documentation. It goes over the technology and libraries that we use to generate this API reference docs, details the
+docstring style we use, mentions how to add something into the API reference (like new modules) and details what
+should and shouldn't be documented here.
 
 As was already briefly mentioned in the [documentation](./documentation.md) section, we're using
 [mkdocstrings](https://mkdocstrings.github.io/), which is an extension of `mkdocs` that is able to automatically
@@ -170,6 +177,8 @@ document something from the docs directly, rather than just from docstrings.
 Rather than rewriting what's already really well explained, we'll instead just point you towards the [mkdocstrings
 documentation](https://mkdocstrings.github.io/usage/).
 
+## What to document
+
 Finally, before including something into the docs, make sure it makes sense as a part of your Public API. When deciding
 this, you might find this [Griffe
 guide](https://mkdocstrings.github.io/griffe/guide/users/recommendations/public-apis/) to be helpful.

docs/contributing/guides/documentation.md

@@ -25,4 +25,4 @@ some more life to the docs, but aren't something that you'd need to work with al
 it out though, so that you know what's available.
 
 Finally, for generating our API reference page, we're using [mkdocstrings](https://mkdocstrings.github.io/). More on
-that in the [docstrings and reference](./docstrings-and-reference.md) guide though.
+that in the [API reference](./api-reference.md) guide though.

mkdocs.yml

@@ -50,7 +50,7 @@ nav:
           - Breaking Changes: contributing/guides/breaking-changes.md
           - Unit Tests: contributing/guides/unit-tests.md
           - Documentation: contributing/guides/documentation.md
-          - Docstrings and API Reference: contributing/guides/docstrings-and-reference.md
+          - API Reference: contributing/guides/api-reference.md
           - Great commits: contributing/guides/great-commits.md
   - API Reference:
       - Protocol: reference/protocol.md