Minor apidocs cleanups (#827)

* Improve API docs rendering

Remove some of the cruft by using a custom template.

* Fix JS error

* Tweak docstrings

* Remove some blank lines

* Customize layout to get base CSS

* Minor doc tweaks

* Minor issue with hightlight

* Move doctrees

Author: therve

.generator/templates/api.mustache

@@ -87,7 +87,7 @@ class {{classname}}(object):
 {{#allParams}}
                 '{{paramName}}': {
                      {{#required}}'required': True,{{/required}}
-		     {{#isNullable}}'nullable': True,{{/isNullable}}
+                     {{#isNullable}}'nullable': True,{{/isNullable}}
 {{#isEnum}}
                      'allowed_values': {
 {{#isNullable}}
@@ -111,14 +111,14 @@ class {{classname}}(object):
                     },
 {{/hasValidation}}
                     'openapi_types': ({{{dataType}}},),
-		   {{^isBodyParam}}
+                   {{^isBodyParam}}
                     'attribute': '{{baseName}}',
 {{/isBodyParam}}
                     'location': '{{#isFormParam}}form{{/isFormParam}}{{#isQueryParam}}query{{/isQueryParam}}{{#isPathParam}}path{{/isPathParam}}{{#isHeaderParam}}header{{/isHeaderParam}}{{#isCookieParam}}cookie{{/isCookieParam}}{{#isBodyParam}}body{{/isBodyParam}}',
 {{#collectionFormat}}
                     'collection_format': '{{collectionFormat}}',
 {{/collectionFormat}}
-	    },
+            },
 {{/allParams}}
 },
             headers_map={
@@ -170,25 +170,13 @@ class {{classname}}(object):
 
         >>> thread = api.{{operationId}}({{#requiredParams}}{{^defaultValue}}{{paramName}}, {{/defaultValue}}{{/requiredParams}}{{#requiredParams}}{{#defaultValue}}{{paramName}}={{{defaultValue}}}, {{/defaultValue}}{{/requiredParams}}async_req=True)
         >>> result = thread.get()
-{{#requiredParams}}
 
-{{/requiredParams}}
-{{#requiredParams}}
-{{^defaultValue}}{{#description}}
-        :param {{paramName}}: {{{.}}}{{/description}}
+{{#requiredParams}}{{#description}}        :param {{paramName}}: {{{.}}}{{#defaultValue}} Defaults to {{{defaultValue}}}.{{/defaultValue}}{{/description}}
         :type {{paramName}}: {{dataType}}
-{{/defaultValue}}
-{{/requiredParams}}
-{{#requiredParams}}
-{{#defaultValue}}{{#description}}
-        :param {{paramName}}: {{{.}}} Defaults to {{{defaultValue}}}. Must be one of [{{{defaultValue}}}]{{/description}}
-        :type {{paramName}}: {{dataType}}
-{{/defaultValue}}
 {{/requiredParams}}
-    {{#optionalParams}}{{#description}}
-        :param {{paramName}}: {{{.}}}{{#defaultValue}} If omitted the server will use the default value of {{{defaultValue}}}.{{/defaultValue}}{{/description}}
+{{#optionalParams}}{{#description}}        :param {{paramName}}: {{{.}}}{{#defaultValue}} If omitted the server will use the default value of {{{defaultValue}}}.{{/defaultValue}}{{/description}}
         :type {{paramName}}: {{dataType}}, optional
-    {{/optionalParams}}
+{{/optionalParams}}
         :param _return_http_data_only: Response data without head status
             code and headers. Default is True.
         :type _return_http_data_only: bool

.generator/templates/model_templates/methods_setattr_getattr_composed.mustache

@@ -1,5 +1,5 @@
     def __setitem__(self, name, value):
-        """set the value of an attribute using square-bracket notation: `instance[attr] = val`"""
+        """Set the value of an attribute using square-bracket notation: `instance[attr] = val`."""
         if name in self.required_properties:
             self.__dict__[name] = value
             return
@@ -15,7 +15,7 @@
     __unset_attribute_value__ = object()
 
     def get(self, name, default=None):
-        """returns the value of an attribute or some default value if the attribute was not set"""
+        """Returns the value of an attribute or some default value if the attribute was not set."""
         if name in self.required_properties:
             return self.__dict__[name]
 
@@ -46,7 +46,7 @@
             )
 
     def __getitem__(self, name):
-        """get the value of an attribute using square-bracket notation: `instance[attr]`"""
+        """Get the value of an attribute using square-bracket notation: `instance[attr]`."""
         value = self.get(name, self.__unset_attribute_value__)
         if value is self.__unset_attribute_value__:
             raise ApiAttributeError(
@@ -57,7 +57,7 @@
         return value
 
     def __contains__(self, name):
-        """used by `in` operator to check if an attribute value was set in an instance: `'attr' in instance`"""
+        """Used by `in` operator to check if an attribute value was set in an instance: `'attr' in instance`."""
 
         if name in self.required_properties:
             return name in self.__dict__
@@ -70,4 +70,4 @@
                 if name in model_instance._data_store:
                     return True
 
-        return False
+        return False

.generator/templates/model_templates/methods_setattr_getattr_normal.mustache

@@ -1,20 +1,20 @@
     def __setitem__(self, name, value):
-        """set the value of an attribute using square-bracket notation: `instance[attr] = val`"""
+        """Set the value of an attribute using square-bracket notation: `instance[attr] = val`."""
         if name in self.required_properties:
             self.__dict__[name] = value
             return
 
         self.set_attribute(name, value)
 
     def get(self, name, default=None):
-        """returns the value of an attribute or some default value if the attribute was not set"""
+        """Returns the value of an attribute or some default value if the attribute was not set."""
         if name in self.required_properties:
             return self.__dict__[name]
 
         return self.__dict__['_data_store'].get(name, default)
 
     def __getitem__(self, name):
-        """get the value of an attribute using square-bracket notation: `instance[attr]`"""
+        """Get the value of an attribute using square-bracket notation: `instance[attr]`."""
         if name in self:
             return self.get(name)
 
@@ -25,8 +25,8 @@
         )
 
     def __contains__(self, name):
-        """used by `in` operator to check if an attribute value was set in an instance: `'attr' in instance`"""
+        """Used by `in` operator to check if an attribute value was set in an instance: `'attr' in instance`."""
         if name in self.required_properties:
             return name in self.__dict__
 
-        return name in self.__dict__['_data_store']
+        return name in self.__dict__['_data_store']

.generator/templates/model_templates/methods_shared.mustache

@@ -7,9 +7,9 @@
         return not self == other
 
     def __setattr__(self, attr, value):
-        """set the value of an attribute using dot notation: `instance.attr = val`"""
+        """Set the value of an attribute using dot notation: `instance.attr = val`."""
         self[attr] = value
 
     def __getattr__(self, attr):
-        """get the value of an attribute using dot notation: `instance.attr`"""
-        return self.{{#attrNoneIfUnset}}get{{/attrNoneIfUnset}}{{^attrNoneIfUnset}}__getitem__{{/attrNoneIfUnset}}(attr)
+        """Get the value of an attribute using dot notation: `instance.attr`."""
+        return self.{{#attrNoneIfUnset}}get{{/attrNoneIfUnset}}{{^attrNoneIfUnset}}__getitem__{{/attrNoneIfUnset}}(attr)

.generator/templates/model_utils.mustache

@@ -1796,7 +1796,7 @@ def validate_get_composed_info(constant_args, model_args, self):
             additional_properties_type. This list can include self
     :rtype: list
     """
-    # create composed_instances
+    # Create composed_instances
     composed_instances = []
     allof_instances = get_allof_instances(self, model_args, constant_args)
     composed_instances.extend(allof_instances)
@@ -1805,34 +1805,14 @@ def validate_get_composed_info(constant_args, model_args, self):
         composed_instances.append(oneof_instance)
     anyof_instances = get_anyof_instances(self, model_args, constant_args)
     composed_instances.extend(anyof_instances)
-    """
-    set additional_properties_model_instances
-    additional properties must be evaluated at the schema level
-    so self's additional properties are most important
-    If self is a composed schema with:
-    - no properties defined in self
-    - additionalProperties: False
-    Then for object payloads every property is an additional property
-    and they are not allowed, so only empty dict is allowed
-
-    Properties must be set on all matching schemas
-    so when a property is assigned toa composed instance, it must be set on all
-    composed instances regardless of additionalProperties presence
-    keeping it to prevent breaking changes in v5.0.1
-    TODO remove cls._additional_properties_model_instances in 6.0.0
-    """
+
     additional_properties_model_instances = []
     if self.additional_properties_type is not None:
         additional_properties_model_instances = [self]
 
-    """
-    no need to set properties on self in here, they will be set in __init__
-    By here all composed schema oneOf/anyOf/allOf instances have their properties set using
-    model_args
-    """
     discarded_args = get_discarded_args(self, composed_instances, model_args)
 
-    # map variable names to composed_instances
+    # Map variable names to composed_instances
     var_name_to_model_instances = {}
     for prop_name in model_args:
         if prop_name not in discarded_args:

.github/workflows/docs.yml

@@ -32,7 +32,7 @@ jobs:
       - name: Cache sphinx
         uses: actions/cache@v2
         with:
-          path: site
+          path: docs/.sphinx
           key: sphinx
 
       - name: Build documentation

.gitignore

@@ -3,6 +3,7 @@ src/datadog_api_client/version.py
 .generator/lib
 examples/generated
 site
+docs/.sphinx
 
 # VSCode
 .vscode

.pre-commit-config.yaml

@@ -24,7 +24,7 @@ repos:
     name: Generate API docs
     stages: [manual]
     language: python
-    entry: sphinx-apidoc --output-dir docs --force --no-toc src/datadog_api_client *apis *models *version.py
+    entry: sphinx-apidoc --output-dir docs --force --no-toc --templatedir docs/_templates src/datadog_api_client *apis *models *version.py
     pass_filenames: false
     additional_dependencies:
       - Sphinx

docs/_templates/layout.html

@@ -0,0 +1,12 @@
+{%- extends "!layout.html" %}
+
+{%- block extrahead %}
+    <link rel="stylesheet" href="{{ pathto('_static/basic.css', 1) }}"/>
+    <style>
+    dt:target {
+      background-color: white;
+    }
+    </style>
+
+  {{ super() }}
+{% endblock %}

docs/_templates/package.rst_t

@@ -0,0 +1,43 @@
+{%- macro automodule(modname, options) -%}
+.. automodule:: {{ modname }}
+{%- for option in options %}
+   :{{ option }}:
+{%- endfor %}
+{%- endmacro %}
+
+{%- macro toctree(docnames) -%}
+.. toctree::
+   :maxdepth: {{ maxdepth }}
+{% for docname in docnames %}
+   {{ docname }}
+{%- endfor %}
+{%- endmacro %}
+
+{{- pkgname | e | heading }}
+
+{%- if modulefirst %}
+{{ automodule(pkgname, automodule_options) }}
+{% endif %}
+
+{%- if subpackages %}
+
+{{ toctree(subpackages) }}
+{% endif %}
+
+{%- if submodules %}
+{% if separatemodules %}
+{{ toctree(submodules) }}
+{% else %}
+{%- for submodule in submodules %}
+{% if show_headings %}
+{{- submodule.split(".")[-1] | e | heading(2) }}
+{% endif %}
+{{ automodule(submodule, automodule_options) }}
+{% endfor %}
+{%- endif %}
+{%- endif %}
+
+{%- if not modulefirst %}
+
+{{ automodule(pkgname, automodule_options) }}
+{% endif %}