Update autodoc defaults (#3369)

Aidan-McNay · EnricoMi · web-flow · commit 0b4503cb6dab · 2025-09-26T08:24:55.000Z
Looking between the documentation for `v2.7.0` and `v2.8.0`, all member function documentation has vanished, making it extremely difficult to utilize the documentation and for new users to be acquainted with the library. This appears to be from a [change in Sphinx](https://www.sphinx-doc.org/en/master/extdev/deprecated.html#:~:text=autodoc_default_flags,autodoc_default_options) deprecating `autodoc_default_flags` in favor of `autodoc_default_options`, which was exposed when the Sphinx version was bumped (6f0d6ef) in `requirements/docs.txt`. Let me know if I'm missing anything! Fixes #3373. --------- Co-authored-by: Enrico Minack <github@enrico.minack.dev>
diff --git a/doc/conf.py b/doc/conf.py
@@ -275,7 +275,7 @@
 # How to display URL addresses: 'footnote', 'no', or 'inline'.
 # texinfo_show_urls = 'footnote'
 
-autodoc_default_flags = ["members"]
+autodoc_default_options = {"members": True}
 autodoc_member_order = "bysource"
 autoclass_content = "both"
 
diff --git a/doc/utilities.rst b/doc/utilities.rst
@@ -21,14 +21,7 @@ Logging
 Error Handling
 --------------
 
-.. autoclass:: github.GithubException
-.. autoclass:: github.BadAttributeException
-.. autoclass:: github.BadCredentialsException
-.. autoclass:: github.TwoFactorException
-.. autoclass:: github.BadUserAgentException
-.. autoclass:: github.RateLimitExceededException
-.. autoclass:: github.IncompletableObject
-.. autoclass:: github.UnknownObjectException
+.. automodule:: github.GithubException
 
 Default argument
 ----------------
diff --git a/github/GitRelease.py b/github/GitRelease.py
@@ -312,7 +312,7 @@ def upload_asset(
         self, path: str, label: str = "", content_type: Opt[str] = NotSet, name: Opt[str] = NotSet
     ) -> github.GitReleaseAsset.GitReleaseAsset:
         """
-        :calls: `POST https://<upload_url>/repos/{owner}/{repo}/releases/{release_id}/assets <https://docs.github.com/en/rest/releases/assets?apiVersion=2022-11-28#upload-a-release-assett>`_
+        :calls: `POST https://<upload_url>/repos/{owner}/{repo}/releases/{release_id}/assets <https://docs.github.com/en/rest/releases/assets?apiVersion=2022-11-28#upload-a-release-assett>`__
         """
         assert isinstance(path, str), path
         assert isinstance(label, str), label
@@ -348,7 +348,7 @@ def upload_asset_from_memory(
 
         Unlike ``upload_asset()`` this method allows you to pass in a file-like object to upload.
         Note that this method is more strict and requires you to specify the ``name``, since there's no file name to infer these from.
-        :calls: `POST https://<upload_url>/repos/{owner}/{repo}/releases/{release_id}/assets <https://docs.github.com/en/rest/reference/repos#upload-a-release-asset>`_
+        :calls: `POST https://<upload_url>/repos/{owner}/{repo}/releases/{release_id}/assets <https://docs.github.com/en/rest/reference/repos#upload-a-release-asset>`__
         :param file_like: binary file-like object, such as those returned by ``open("file_name", "rb")``. At the very minimum, this object must implement ``read()``.
         :param file_size: int, size in bytes of ``file_like``
 
diff --git a/github/GithubIntegration.py b/github/GithubIntegration.py
@@ -285,9 +285,7 @@ def get_installation(self, owner: str, repo: str) -> Installation:
         """
         Deprecated by get_repo_installation.
 
-        :calls:`GET /repos/{owner}/{repo}/installation <https://docs.github.com/en/rest/reference/apps#get-a-repository-
-        installation-for-the-authenticated-app>`
-        :calls:`GET /repos/{owner}/{repo}/installation <https://docs.github.com/en/rest/reference/apps#get-a-repository-
+        :calls: `GET /repos/{owner}/{repo}/installation <https://docs.github.com/en/rest/reference/apps#get-a-repository-
         installation-for-the-authenticated-app>`
 
         """
diff --git a/github/IssueComment.py b/github/IssueComment.py
@@ -229,8 +229,8 @@ def delete_reaction(self, reaction_id: int) -> bool:
 
     def minimize(self, reason: str = "OUTDATED") -> bool:
         """
-        :calls: `POST /graphql <https://docs.github.com/en/graphql>`_ with a mutation to minimize comment
-        <https://docs.github.com/en/graphql/reference/mutations#minimizecomment>
+        :calls: `POST /graphql <https://docs.github.com/en/graphql>`__ with a mutation to minimize comment
+            <https://docs.github.com/en/graphql/reference/mutations#minimizecomment>
         """
         assert isinstance(reason, str), reason
         variables = {
@@ -246,8 +246,8 @@ def minimize(self, reason: str = "OUTDATED") -> bool:
 
     def unminimize(self) -> bool:
         """
-        :calls: `POST /graphql <https://docs.github.com/en/graphql>`_ with a mutation to unminimize comment
-        <https://docs.github.com/en/graphql/reference/mutations#unminimizecomment>
+        :calls: `POST /graphql <https://docs.github.com/en/graphql>`__ with a mutation to unminimize comment
+            <https://docs.github.com/en/graphql/reference/mutations#unminimizecomment>
         """
         variables = {
             "subjectId": self.node_id,
diff --git a/github/MainClass.py b/github/MainClass.py
@@ -356,7 +356,7 @@ def get_rate_limit(self) -> RateLimitOverview:
         """
         Rate limit overview that provides general status and status for different resources (core/search/graphql).
 
-        :calls:`GET /rate_limit <https://docs.github.com/en/rest/reference/rate-limit>`_
+        :calls: `GET /rate_limit <https://docs.github.com/en/rest/reference/rate-limit>`_
 
         """
         headers, data = self.__requester.requestJsonAndCheck("GET", "/rate_limit")
@@ -1000,26 +1000,6 @@ def dump(self, obj: GithubObject, file: BinaryIO, protocol: int = 0) -> None:
         information like the Github credentials used in the :class:`Github` instance. But NO EFFORT is made to remove
         sensitive information from the object's attributes.
 
-        :param obj: the object to pickle :param file: the file-like object to pickle to :param protocol: the
-        `pickling protocol <https://python.readthedocs.io/en/latest/library/pickle.html#data-stream-format>`_
-         :param obj: the object to pickle :param file: the file-like object to pickle to :param protocol: the
-        `pickling protocol <https://python.readthedocs.io/en/latest/library/pickle.html#data-
-         :param obj: the object to pickle :param file: the file-like object to pickle to :param protocol: the
-        `pickling protocol <https://python.readthedocs.io/en/latest/library/pickle.html#data-
-             stream-format>`_ :param obj: the object to pickle :param file: the file-like object to pickle to :param
-        protocol: the
-        `pickling protocol <https://python.readthedocs.io/en/latest/library/pickle.html#data-
-        :param obj: the object to pickle
-        :param file: the file-like object to pickle to
-        :param protocol: the `pickling protocol <https://python.readthedocs.io/en/latest/library/pickle.html#data-
-            stream-format>`_
-        :param obj: the object to pickle
-        :param file: the file-like object to pickle to
-        :param protocol: the `pickling protocol <https://python.readthedocs.io/en/latest/library/pickle.html#data-
-        :param obj: the object to pickle
-        :param file: the file-like object to pickle to
-        :param protocol: the `pickling protocol <https://python.readthedocs.io/en/latest/library/pickle.html#data-
-            stream-format>`_
         :param obj: the object to pickle
         :param file: the file-like object to pickle to
         :param protocol: the `pickling protocol <https://python.readthedocs.io/en/latest/library/pickle.html#data-
diff --git a/github/PullRequest.py b/github/PullRequest.py
@@ -883,7 +883,7 @@ def enable_automerge(
     ) -> dict[str, Any]:
         """
         :calls: `POST /graphql <https://docs.github.com/en/graphql>`_ with a mutation to enable pull request auto merge
-        <https://docs.github.com/en/graphql/reference/mutations#enablepullrequestautomerge>
+            <https://docs.github.com/en/graphql/reference/mutations#enablepullrequestautomerge>
         """
         assert is_optional(author_email, str), author_email
         assert is_optional(client_mutation_id, str), client_mutation_id
@@ -917,7 +917,7 @@ def disable_automerge(
     ) -> dict[str, Any]:
         """
         :calls: `POST /graphql <https://docs.github.com/en/graphql>`_ with a mutation to disable pull request auto merge
-        <https://docs.github.com/en/graphql/reference/mutations#disablepullrequestautomerge>
+            <https://docs.github.com/en/graphql/reference/mutations#disablepullrequestautomerge>
         """
         assert is_optional(client_mutation_id, str), client_mutation_id
 
@@ -1013,7 +1013,7 @@ def convert_to_draft(
     ) -> dict[str, Any]:
         """
         :calls: `POST /graphql <https://docs.github.com/en/graphql>`_ to convert pull request to draft
-        <https://docs.github.com/en/graphql/reference/mutations#convertpullrequesttodraft>
+            <https://docs.github.com/en/graphql/reference/mutations#convertpullrequesttodraft>
         """
         assert is_optional(client_mutation_id, str), client_mutation_id
 
@@ -1038,7 +1038,7 @@ def mark_ready_for_review(
     ) -> dict[str, Any]:
         """
         :calls: `POST /graphql <https://docs.github.com/en/graphql>`_ to mark pull request ready for review
-        <https://docs.github.com/en/graphql/reference/mutations#markpullrequestreadyforreview>
+            <https://docs.github.com/en/graphql/reference/mutations#markpullrequestreadyforreview>
         """
         assert is_optional(client_mutation_id, str), client_mutation_id
 
diff --git a/github/Repository.py b/github/Repository.py
@@ -2515,7 +2515,7 @@ def get_deployments(
     def get_deployment(self, id_: int) -> Deployment:
         """
         :calls: `GET /repos/{owner}/{repo}/deployments/{deployment_id} <https://docs.github.com/en/rest/reference/repos#deployments>`_
-        :param: id_: int
+        :param: id: int
         :rtype: :class:`github.Deployment.Deployment`
         """
         assert isinstance(id_, int), id_
@@ -3462,7 +3462,7 @@ def get_pulls_comments(
         since: Opt[datetime] = NotSet,
     ) -> PaginatedList[PullRequestComment]:
         """
-        :calls: `GET /repos/{owner}/{repo}/pulls/comments <https://docs.github.com/en/rest/reference/pulls#comments>`_
+        :calls: `GET /repos/{owner}/{repo}/pulls/comments <https://docs.github.com/en/rest/reference/pulls#comments>`__
         :param sort: string
         :param direction: string
         :param since: datetime
@@ -3477,7 +3477,7 @@ def get_pulls_review_comments(
         since: Opt[datetime] = NotSet,
     ) -> PaginatedList[PullRequestComment]:
         """
-        :calls: `GET /repos/{owner}/{repo}/pulls/comments <https://docs.github.com/en/rest/reference/pulls#review-comments>`_
+        :calls: `GET /repos/{owner}/{repo}/pulls/comments <https://docs.github.com/en/rest/reference/pulls#review-comments>`_:
         :param sort: string 'created', 'updated', 'created_at'
         :param direction: string 'asc' or 'desc'
         :param since: datetime
