aboutsummaryrefslogtreecommitdiffstats
path: root/docs/utils.py
diff options
context:
space:
mode:
authorGravatar Hassan Abouelela <[email protected]>2022-11-10 22:21:42 +0400
committerGravatar Hassan Abouelela <[email protected]>2022-11-10 22:21:42 +0400
commit2b6fe6eb8a0618a0d305ecfd88a10dc0ec8dec2c (patch)
tree6c87d8bb4e2e8491eb8a9c76b8606e4a4f55cd80 /docs/utils.py
parentMerge pull request #157 from python-discord/prepare-for-pypi-release (diff)
Add Support For Attributes In Docstrings
This allows class attributes to be defined in docstrings without causing an exception while linking the source code. Due to the non-static nature of attributes, it's not trivial to link their actual definition, so the chosen lines will actually be all the lines of the parent class. Signed-off-by: Hassan Abouelela <[email protected]>
Diffstat (limited to 'docs/utils.py')
-rw-r--r--docs/utils.py24
1 files changed, 23 insertions, 1 deletions
diff --git a/docs/utils.py b/docs/utils.py
index e7295798..ba6c8e34 100644
--- a/docs/utils.py
+++ b/docs/utils.py
@@ -5,9 +5,11 @@ import importlib.util
import inspect
import os
import subprocess
+import types
import typing
from pathlib import Path
+import docstring_parser
import docutils.nodes
import docutils.parsers.rst.states
import git
@@ -25,6 +27,18 @@ def get_build_root() -> Path:
return root
+def is_attribute(module: types.ModuleType, parameter: str) -> bool:
+ """Returns true if `parameter` is an attribute of `module`."""
+ docs = docstring_parser.parse(inspect.getdoc(module), docstring_parser.DocstringStyle.GOOGLE)
+ for param in docs.params:
+ # The docstring_parser library can mis-parse arguments like `arg (:obj:`str`)` as `arg (`
+ # which would create a false-negative below, so we just strip away the extra parenthesis.
+ if param.args[0] == "attribute" and param.arg_name.rstrip(" (") == parameter:
+ return True
+
+ return False
+
+
def linkcode_resolve(repo_link: str, domain: str, info: dict[str, str]) -> typing.Optional[str]:
"""
Function called by linkcode to get the URL for a given resource.
@@ -59,7 +73,15 @@ def linkcode_resolve(repo_link: str, domain: str, info: dict[str, str]) -> typin
symbol = [module]
for name in symbol_name.split("."):
- symbol.append(getattr(symbol[-1], name))
+ try:
+ symbol.append(getattr(symbol[-1], name))
+ except AttributeError as e:
+ # This could be caused by trying to link a class attribute
+ if is_attribute(symbol[-1], name):
+ break
+ else:
+ raise e
+
symbol_name = name
try: