💡 Docs: add more info to rest api methods' docstring (#210)

Author: yanyongyu

codegen/pyproject.toml

@@ -5,13 +5,3 @@ target-version = "py310"
 
 [tool.ruff.lint]
 ignore = ["TID"]
-
-[tool.pyright]
-typeCheckingMode = "standard"
-reportPrivateImportUsage = false
-reportShadowedImports = false
-disableBytesTypePromotions = true
-
-pythonVersion = "3.10"
-pythonPlatform = "All"
-defineConstant = { PYDANTIC_V2 = true }

codegen/templates/rest/_docstring.py.jinja

@@ -0,0 +1,15 @@
+{% macro build_docstring(endpoint) %}
+"""{% if endpoint.deprecated %}DEPRECATED {% endif %}{% if endpoint.operation_id %}{{ endpoint.operation_id }}
+{% endif %}
+
+{{ endpoint.method | upper }} {{ endpoint.path }}
+{% if endpoint.description %}
+
+{{ endpoint.description }}
+{% endif %}
+{% if endpoint.external_docs %}
+
+See also: {{ endpoint.external_docs }}
+{% endif %}
+"""
+{% endmacro %}

codegen/templates/rest/client.py.jinja

@@ -5,6 +5,7 @@
 {% from "rest/_param.py.jinja" import endpoint_params, endpoint_raw_params, endpoint_model_params %}
 {% from "rest/_response.py.jinja" import build_response_type %}
 {% from "rest/_request.py.jinja" import build_request, build_request_params %}
+{% from "rest/_docstring.py.jinja" import build_docstring %}
 
 from __future__ import annotations
 
@@ -98,10 +99,8 @@ class {{ pascal_case(tag) }}Client:
         self,
         {{ endpoint_params(endpoint) | indent(8) }}
     ) -> {{ build_response_type(endpoint.success_response) }}:
-        {% if endpoint.external_docs %}
-        """See also: {{ endpoint.external_docs }}"""
+        {{ build_docstring(endpoint) | indent(8) }}
 
-        {% endif %}
         {{ build_request(endpoint) | indent(8) }}
         return self._github.request(
             {{ build_request_params(endpoint) | indent(12) }}
@@ -131,10 +130,8 @@ class {{ pascal_case(tag) }}Client:
         self,
         {{ endpoint_params(endpoint) | indent(8) }}
     ) -> {{ build_response_type(endpoint.success_response) }}:
-        {% if endpoint.external_docs %}
-        """See also: {{ endpoint.external_docs }}"""
+        {{ build_docstring(endpoint) | indent(8) }}
 
-        {% endif %}
         {{ build_request(endpoint) | indent(8) }}
         return await self._github.arequest(
             {{ build_request_params(endpoint) | indent(12) }}

pyproject.toml

@@ -140,6 +140,7 @@ defineConstant = { PYDANTIC_V2 = true }
 executionEnvironments = [
   # disable overload check for generated version codes
   { root = "githubkit/versions/", reportOverlappingOverload = false },
+  { root = "codegen", pythonVersion = "3.10" },
 ]
 
 exclude = ["codegen/**"]

scripts/run-codegen.sh

@@ -5,4 +5,4 @@ set -e
 # cd to the root of the project
 cd "$(dirname "$0")/.."
 
-python -m codegen && ruff check --select I --fix --exit-zero . && ruff check --fix --exit-zero . && ruff format .
+python -m codegen && ruff check --select I --fix --exit-zero . && ruff check --fix --exit-zero . && ruff format . && ruff check --fix .