Generate docs using sphinx (#820)

* Use sphinx to generate docs

* Remove generated docs

* Ignore some files in git

* Switch them, remove version

* Cleanup conf

* Fix CI and nav

* Add cache, fix version pattern

* Tweak readme

Author: therve

.github/workflows/docs.yml

@@ -29,13 +29,22 @@ jobs:
       - name: Install tox
         run: pip install tox
 
+      - name: Cache sphinx
+        uses: actions/cache@v2
+        with:
+          path: site
+          key: sphinx
+
       - name: Build documentation
-        run: tox -e docs build
+        run: tox -e docs
+
+      - name: Compress site
+        run: tar czf site.tar.gz site
 
       - uses: actions/upload-artifact@v2
         with:
           name: documentation
-          path: site
+          path: site.tar.gz
 
   publish:
     runs-on: ubuntu-latest
@@ -48,7 +57,10 @@ jobs:
       - uses: actions/download-artifact@v2
         with:
           name: documentation
-          path: site
+          path: site.tar.gz
+
+      - name: Uncompress site
+        run: tar xzf site.tar.gz
 
       - uses: peaceiris/actions-gh-pages@v3
         with:

.gitignore

@@ -1,7 +1,9 @@
 .env
-examples/
 src/datadog_api_client/version.py
 .generator/lib
+docs/datadog_api_client*.rst
+examples/generated
+site
 
 # VSCode
 .vscode

.pre-commit-config.yaml

@@ -12,9 +12,9 @@ repos:
     stages: [manual]
     language: node
     language_version: 14.12.0
-    entry: prettier --write --list-different --ignore-unknown docs
+    entry: prettier --write --list-different --ignore-unknown README.md
     "types": [text]
-    files: '^docs/'
+    files: 'README.md'
     pass_filenames: false
     additional_dependencies:
       # When updating the version of prettier, make sure to check the  pre-commit file

Makefile

@@ -1,13 +1,10 @@
 .PHONY: all
 all: .generator .env
 	@pre-commit run --all-files --hook-stage=manual openapi-generator || true
-	@mkdir -p docs/v1 docs/v2
 	@cp -r v1/datadog_api_client ./src/
 	@cp -r v2/datadog_api_client ./src/
-	@cp -r v1/docs/* ./docs/v1/
-	@cp -r v2/docs/* ./docs/v2/
-	@cp v1/README.md ./docs/v1/
-	@cp v2/README.md ./docs/v2/
+	@ls v1/docs/*Api.md | xargs -n1 ./extract-code-blocks.awk -v output="examples/generated/v1"
+	@ls v2/docs/*Api.md | xargs -n1 ./extract-code-blocks.awk -v output="examples/generated/v2"
 	@rm -rf v1 v2
 	@pre-commit run --all-files --hook-stage=manual docs || echo "modified files"
 	@pre-commit run --all-files --hook-stage=manual autoflake || echo "modified files"

README.md

@@ -21,54 +21,25 @@ pip install datadog-api-client
 Please follow the [installation](#installation) instruction and execute the following Python code:
 
 ```python
-import os
-from dateutil.parser import parse as dateutil_parser
-import datadog_api_client.v1
-from datadog_api_client.v1.api import aws_integration_api
-from datadog_api_client.v1.models import *
-from pprint import pprint
-
-# Defining the host is optional and defaults to https://api.datadoghq.com
-# See configuration.py for a list of all supported configuration parameters.
-configuration = datadog_api_client.v1.Configuration(
-    host = "https://api.datadoghq.com"
+from datadog_api_client.v1 import ApiClient, Configuration
+from datadog_api_client.v1.api.monitors_api import MonitorsApi
+from datadog_api_client.v1.model.monitor import Monitor
+from datadog_api_client.v1.model.monitor_type import MonitorType
+
+body = Monitor(
+    name="example",
+    type=MonitorType("log alert"),
+    query='logs("service:foo AND type:error").index("main").rollup("count").by("source").last("5m") > 2',
+    message="some message Notify: @hipchat-channel",
+    tags=["test:example", "env:ci"],
+    priority=3,
 )
 
-# The client must configure the authentication and authorization parameters
-# in accordance with the API server security policy.
-# Examples for each auth method are provided below, use the example that
-# satisfies your auth use case.
-
-# Configure API key authorization: apiKeyAuth
-configuration.api_key['apiKeyAuth'] = os.getenv('DD_CLIENT_API_KEY')
-
-# Configure API key authorization: appKeyAuth
-configuration.api_key['appKeyAuth'] = os.getenv('DD_CLIENT_APP_KEY')
-
-# Enter a context with an instance of the API client
-with datadog_api_client.v1.ApiClient(configuration) as api_client:
-    # Create an instance of the API class
-    api_instance = aws_integration_api.AWSIntegrationApi(api_client)
-    body = AWSAccount(
-        access_key_id="access_key_id_example",
-        account_id="1234567",
-        account_specific_namespace_rules={
-            "key": True,
-        },
-        excluded_regions=["us-east-1","us-west-2"],
-        filter_tags=["<KEY>:<VALUE>"],
-        host_tags=["<KEY>:<VALUE>"],
-        role_name="DatadogAWSIntegrationRole",
-        secret_access_key="secret_access_key_example",
-    ) # AWSAccount | AWS Request Object
-
-    # example passing only required values which don't have defaults set
-    try:
-        # Create an AWS integration
-        api_response = api_instance.create_aws_account(body)
-        pprint(api_response)
-    except datadog_api_client.v1.ApiException as e:
-        print("Exception when calling AWSIntegrationApi->create_aws_account: %s\n" % e)
+configuration = Configuration()
+with ApiClient(configuration) as api_client:
+    api_instance = MonitorsApi(api_client)
+    response = api_instance.create_monitor(body=body)
+    print(response)
 ```
 
 ### Unstable Endpoints
@@ -113,7 +84,6 @@ the API methods will then return coroutines that you can wait for.
 
 To make async support available, you need to install the extra `async` qualifiers during installation: `pip install datadog-api-client[async]`.
 
-
 ```python
 import asyncio
 
@@ -132,9 +102,7 @@ asyncio.run(main())
 
 ## Documentation for API Endpoints and Models
 
-Documentation for API endpoints and models can be found under the docs subdirectories, in [v1](/docs/v1#documentation-for-api-endpoints) and [v2](/docs/v2#documentation-for-api-endpoints).
-
-It's also available on [readthedocs](https://datadog-api-client.readthedocs.io/).
+Documentation for API endpoints and models are available on [readthedocs](https://datadog-api-client.readthedocs.io/).
 
 ## Documentation for Authorization
 
@@ -148,4 +116,3 @@ configuration.api_key["appKeyAuth"] = "YOUR_APPLICATION_KEY"
 ## Author
 
 [email protected]
-

docs/README.md

@@ -0,0 +1,69 @@
+# -- Path setup --------------------------------------------------------------
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+#
+import os
+import sys
+
+sys.path.insert(0, os.path.abspath("../src"))
+
+
+# -- Project information -----------------------------------------------------
+
+project = "Datadog API Client for Python"
+copyright = "2022, Datadog"
+author = "Datadog"
+
+# -- General configuration ---------------------------------------------------
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+extensions = ["m2r2", "sphinx.ext.autodoc"]
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ["_templates"]
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This pattern also affects html_static_path and html_extra_path.
+exclude_patterns = []
+
+
+# -- Options for HTML output -------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+#
+html_theme = "sphinx_material"
+
+html_logo = "assets/images/logo.svg"
+html_favicon = "assets/images/favicon.ico"
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path = ["assets"]
+
+html_sidebars = {
+    "**": ["globaltoc.html", "localtoc.html", "searchbox.html"]
+}
+
+html_theme_options = {
+    # Set the name of the project to appear in the navigation.
+    "nav_title": "Datadog API Client for Python",
+    # Set the color and the accent color
+    "color_primary": "deep-purple",
+    "color_accent": "deep-purple",
+    # Set the repo location to get a badge with stats
+    "repo_url": "https://github.com/DataDog/datadog-api-client-python/",
+    "repo_name": "datadog-api-client-python",
+    # Visible levels of the global TOC; -1 means unlimited
+    "globaltoc_depth": 3,
+    # If False, expand all TOC entries
+    "globaltoc_collapse": False,
+    # If True, show hidden TOC entries
+    "globaltoc_includehidden": False,
+}