英文:
How to document callable classes annotated with @dataclass in sphinx?
问题
I researched this topic and cannot see a clear solution. There is a similar SO question
My problem is that I have a class with attr.dataclass
and typing_extensions.final
annotations and I don't want them to be documented but I still want to describe the class from the point of how it would be called.
For instance,
@final
@dataclass(frozen=True, slots=True)
class Casting(object):
_int_converter_function = int
_float_converter_function = float
def __call__(self, casting, value_to_cast):
if casting['type'] == 'integer':
return self._int_converter_function(value_to_cast)
return self._float_converter_function(value_to_cast)
This is approximately equivalent to this (which is far away from being accurate):
class Casting(object):
def __init__(
self,
int_converter_function = int,
float_converter_function = float,
):
self.int_converter_function = int_converter_function
self.float_converter_function = float_converter_function
def converter(self, casting, value):
self.value = value
yield
type = casting['type']
if type == 'integer':
yield self.int_converter_function(value)
else:
yield self.float_converter_function(value)
and with the latest it is clear that I can document each method with docstrings and in Sphinx
do:
.. autoclass:: package.Casting
:members:
.. automethod:: __init__(self, int_converter_function, float_converter_function)
How to do the same with annotations?
UPDATE:
I figured out that my questions should be more specific. I want to
-
Eliminate
dataclass
completely from the doc but nevertheless, keep the class in the documentation. It messes classes so much that the docs are unreadable. -
Make a docstring on the
__init__
but also keep it separate from the callable description. I left a comment.
Example of the doc:
"""Cast one type of code to another.
Constructor arguments:
:param int_converter_function: function to convert to int
:param float_converter_function: function to convert to float
Callable arguments:
:param casting: :term:`casting` object
:type casting: dict
:param value_to_cast: input value
:return: Casted value
Example
>>> cast = Casting(int)
>>> cast({'type': 'integer'}, '123')
123
>>> cast({'type': 'decimal'}, '123.12')
Decimal('123.12')
"""
UPDATE 2:
The full class as it is below:
# -*- coding: utf-8 -*-
from attr import dataclass
from typing_extensions import final
@final
@dataclass(frozen=True, slots=True)
class Casting(object):
"""Cast one type of code to another.
Constructor arguments:
:param int_converter_function: function to convert to int
:param float_converter_function: function to convert to float
Callable arguments:
:param casting: :term:`casting` object
:type casting: dict
:param value_to_cast: input value
:return: Casted value
Example
>>> cast = Casting(int)
>>> cast({'type': 'integer'}, '123')
123
>>> cast({'type': 'decimal'}, '123.12')
Decimal('123.12')
"""
_int_converter_function = int
_float_converter_function = float
def __call__(self, casting, value_to_cast):
if casting['type'] == 'integer':
return self._int_converter_function(value_to_cast)
return self._float_converter_function(value_to_cast)
I want to eliminate package.casting.dataclass
from the doc.
英文:
I researched this topic and cannot see a clear solution. There is a similar SO question
My problem is that I have a class with attr.dataclass
and typing_extensions.final
annotations and I don't want them to be documented but I still want to describe the class from the point of how it would be called.
For instance,
@final
@dataclass(frozen=True, slots=True)
class Casting(object):
_int_converter_function = int
_float_converter_function = float
def __call__(self, casting, value_to_cast):
if casting['type'] == 'integer':
return self._int_converter_function(value_to_cast)
return self._float_converter_function(value_to_cast)
This is approximately equivalent to this (which is far away from being accurate):
class Casting(object):
def __init__(
self,
int_converter_function = int,
float_converter_function = float,
):
self.int_converter_function = int_converter_function
self.float_converter_function = float_converter_function
def converter(self, casting, value):
self.value = value
yield
type = casting['type']
if type == 'integer':
yield self.int_converter_function(value)
else:
yield self.float_converter_function(value)
and with the latest it is clear that I can document each method with docstrings and in Sphinx
do:
.. autoclass:: package.Casting
:members:
.. automethod:: __init__(self, int_converter_function, float_converter_function)
How to do the same with annotations?
UPDATE:
I figured out that my questions should be more specific. I want to
-
Eliminate
dataclass
completely from the doc but nevertheless, keep the class in the documentation. It messes classes so much that the docs are unreadable. -
Make a docstring on the
__init__
but also keep it separate from the callable description. I left a comment.
Example of the doc:
"""Cast one type of code to another.
Constructor arguments:
:param int_converter_function: function to convert to int
:param float_converter_function: function to convert to float
Callable arguments:
:param casting: :term:`casting` object
:type casting: dict
:param value_to_cast: input value
:return: Casted value
Example
>>> cast = Casting(int)
>>> cast({'type': 'integer'}, '123')
123
>>> cast({'type': 'decimal'}, '123.12')
Decimal('123.12')
"""
UPDATE 2:
The full class as it is below:
# -*- coding: utf-8 -*-
from attr import dataclass
from typing_extensions import final
@final
@dataclass(frozen=True, slots=True)
class Casting(object):
"""Cast one type of code to another.
Constructor arguments:
:param int_converter_function: function to convert to int
:param float_converter_function: function to convert to float
Callable arguments:
:param casting: :term:`casting` object
:type casting: dict
:param value_to_cast: input value
:return: Casted value
Example
>>> cast = Casting(int)
>>> cast({'type': 'integer'}, '123')
123
>>> cast({'type': 'decimal'}, '123.12')
Decimal('123.12')
"""
_int_converter_function = int
_float_converter_function = float
def __call__(self, casting, value_to_cast):
if casting['type'] == 'integer':
return self._int_converter_function(value_to_cast)
return self._float_converter_function(value_to_cast)
I want to eliminate package.casting.dataclass
from the doc.
答案1
得分: 2
如 @mzjn 在评论中提到的,如果 automodule
配置正确,:exclude-members: dataclass
应该能够完成任务。
我犯了一个愚蠢的错误,很难追踪。如果你将 :exclude-members:
和 <name-of-module>
写在不同的行上,那么文件中的所有类都将被忽略。
与创建构造函数和可调用函数相关的另一部分看起来很不错,我将其提取到了单独的SO问题中。
英文:
As @mzjn mentioned in comments :exclude-members: dataclass
should do the job if automodule
configured correctly.
I made a dumb mistake that was hard to track. If you write :exclude-members:
and <name-of-module>
on the separate lines then all classes in the file will be ignored.
Another part related to make constructor and callable function looks pretty I extracted into separate SO question.
通过集体智慧和协作来改善编程学习和解决问题的方式。致力于成为全球开发者共同参与的知识库,让每个人都能够通过互相帮助和分享经验来进步。
评论