[SYNPY-1360] Migrating to mkdocstrings (#1025)

* Migrating to mkdocstrings

.github/workflows/build-docs.yml

@@ -0,0 +1,27 @@
+name: Build Docs
+on:
+  push:
+    branches:
+      - master
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Configure Git Credentials
+        run: |
+          git config user.name github-actions[bot]
+          git config user.email 41898282+github-actions[bot]@users.noreply.github.com
+      - uses: actions/setup-python@v4
+        with:
+          python-version: 3.x
+      - run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV
+      - uses: actions/cache@v3
+        with:
+          key: mkdocs-material-${{ env.cache_id }}
+          path: .cache
+          restore-keys: |
+            mkdocs-material-
+      - run: pip install mkdocs-material mkdocstrings mkdocstrings-python termynal
+      - run: mkdocs gh-deploy --force

.readthedocs.yaml

@@ -1,5 +1,4 @@
-# .readthedocs.yaml
-# Read the Docs configuration file
+# Read the Docs configuration file for MkDocs projects
 # See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
 
 # Required
@@ -10,20 +9,11 @@ build:
   os: ubuntu-20.04
   tools:
     python: "3.9"
-    # You can also specify other tool versions:
-    # nodejs: "16"
-    # rust: "1.55"
-    # golang: "1.17"
 
-# Build documentation in the docs/ directory with Sphinx
-sphinx:
-   configuration: docs/conf.py
-
-# If using Sphinx, optionally build your docs in additional formats such as PDF
-# formats:
-#    - pdf
+mkdocs:
+  configuration: mkdocs.yml
 
 # Optionally declare the Python requirements required to build your docs
 python:
-   install:
-   - requirements: docs/requirements.txt
+  install:
+  - requirements: docs/requirements.txt

CONTRIBUTING.md

@@ -21,6 +21,7 @@ By contributing, you are agreeing that we may redistribute your work under this
    * [OpenTelemetry](#opentelemetry)
       + [Attributes within traces](#attributes-within-traces)
       + [Adding new spans](#adding-new-spans)
+   * [Python doc pages](#python-doc-pages)
    * [Repository Admins](#repository-admins)
 
 ## I don't want to read this whole thing I just have a question!
@@ -207,6 +208,38 @@ pip install flake8
 flake8
 ```
 
+In addition it is expected that all docstrings follow the google python style
+guide [here](https://google.github.io/styleguide/pyguide.html). In particular this is
+needed as this is how our auto-doc creates our python documentation pages. We should
+be creating the docstrings without types.
+
+#### Some additional expectations:
+- Any new dataclasses should document the class attributes in both a docstring and under the class attribute itself. This is in effect until pylance resolves: https://github.com/microsoft/pylance-release/discussions/4759
+- Create 1 or more examples of all new functions you create. An example format of a function is below. Not the specific spacing and tabbing is required for it to show up as a code block.:
+```
+@dataclass
+class MyDataClass:
+    """
+    The description of this class
+
+    Attributes:
+        my_attribute: My attribute description.
+
+    Example: Example
+        Doing something cool
+
+            my_instance = MyDataClass()
+
+        Doing something else cool
+
+            my_instance = MyDataClass()
+    """
+
+    my_attribute: bool = None
+    """My attribute description."""
+```
+- mkdocstrings has an autorefs plugin that allows you to link to other resources like: `[synapseclient.entity.Project][]`
+
 ### OpenTelemetry
 [OpenTelemetry](https://opentelemetry.io/) helps support the analysis of traces and spans which can provide insights into latency, errors, and other performance metrics. During development it may prove useful to collect information about the execution of your code. The following is meant to be a starting point for additions to the current traces being collected.
 
@@ -224,6 +257,31 @@ All synapse related attributes should live within the `synapse` namespace, for e
     * "Is this an external call or an entry point into the python client?"
     * "Is it useful to know how long this section of code takes to execute?"
 
+### Python doc pages
+The core of the doc pages is `mkdocstrings`. It is a series to markdown pages that use a few
+plugins to link to other documents (aka: `autorefs`).
+
+#### Running the documents page on your local machine
+At the root directory of the project you'll find a `mkdocs.yml`, this is where all commands
+are ran from.
+
+To start a local HTTP server to host the documents use:
+```bash
+mkdocs serve
+```
+
+On push to the master branch the github workflow `build-docs.yml` is set to automatically
+use the `mkdocs gh-deploy` command to build and deploy changes to the live doc site.
+
+#### Guidelines for new documents
+In each of the docs folders there articles live there is a README with further information about the expected content in each folder.
+
+
+Some links for further reading:
+
+- https://mkdocstrings.github.io/
+- https://mkdocstrings.github.io/python/
+
 ### Repository Admins
 
 - [Release process](https://sagebionetworks.jira.com/wiki/spaces/SYNPY/pages/643498030/Synapse+Python+Client+Staging+Validation+Production)