Question: Sphinx changes number system from hexadecimal to decimal for function default arguments Describe the bug When documenting a function, which requires a default argument specified in hexadecimal: Sphinx 3.2.1 will render HTML documentation where the hexadecimal value is in a different number system, than what was specified by the user (decimal), as seen in the following output from the above input: ! Expected behavior The expected behaviour would be to present the default argument in the same radix/number system as the user typed in, thus in this case the documentation would also display the value in hexadecimal. In the above example of with colors, it is unintuitive what the color might refer to, but it's easy read RGB colors in hexadecimal format - e.g. 0xffffff is white, thus which number system is used can make a huge difference. The same for example goes for e.g. specifying access rights for files () Screenshots ! Environment info OS: Mac OS X 10.14.6 Python version: 3.8.5 Sphinx version: 3.2.1 Sphinx extensions: None Extra tools: None

if defaults[i] is Parameter.empty:                 default = Parameter.empty             else:                default = ast_unparse(defaults[i])                default = ast_unparse(defaults[i], code)             annotation = ast_unparse(arg.annotation) or Parameter.empty            annotation = ast_unparse(arg.annotation, code) or Parameter.empty             params.append(Parameter(arg.arg, Parameter.POSITIONAL_ONLY,                                     default=default, annotation=annotation))


Question: Sphinx changes number system from hexadecimal to decimal for function default arguments Describe the bug When documenting a function, which requires a default argument specified in hexadecimal: Sphinx 3.2.1 will render HTML documentation where the hexadecimal value is in a different number system, than what was specified by the user (decimal), as seen in the following output from the above input: ! Expected behavior The expected behaviour would be to present the default argument in the same radix/number system as the user typed in, thus in this case the documentation would also display the value in hexadecimal. In the above example of with colors, it is unintuitive what the color might refer to, but it's easy read RGB colors in hexadecimal format - e.g. 0xffffff is white, thus which number system is used can make a huge difference. The same for example goes for e.g. specifying access rights for files () Screenshots ! Environment info OS: Mac OS X 10.14.6 Python version: 3.8.5 Sphinx version: 3.2.1 Sphinx extensions: None Extra tools: None

if defaults[i + posonlyargs] is Parameter.empty:             default = Parameter.empty         else:            default = ast_unparse(defaults[i + posonlyargs])            default = ast_unparse(defaults[i + posonlyargs], code)         annotation = ast_unparse(arg.annotation) or Parameter.empty        annotation = ast_unparse(arg.annotation, code) or Parameter.empty         params.append(Parameter(arg.arg, Parameter.POSITIONAL_OR_KEYWORD,                                 default=default, annotation=annotation))      if args.vararg:        annotation = ast_unparse(args.vararg.annotation) or Parameter.empty        annotation = ast_unparse(args.vararg.annotation, code) or Parameter.empty         params.append(Parameter(args.vararg.arg, Parameter.VAR_POSITIONAL,                                 annotation=annotation))      for i, arg in enumerate(args.kwonlyargs):        default = ast_unparse(args.kw_defaults[i]) or Parameter.empty        annotation = ast_unparse(arg.annotation) or Parameter.empty        default = ast_unparse(args.kw_defaults[i], code) or Parameter.empty        annotation = ast_unparse(arg.annotation, code) or Parameter.empty         params.append(Parameter(arg.arg, Parameter.KEYWORD_ONLY, default=default,                                 annotation=annotation))      if args.kwarg:        annotation = ast_unparse(args.kwarg.annotation) or Parameter.empty        annotation = ast_unparse(args.kwarg.annotation, code) or Parameter.empty         params.append(Parameter(args.kwarg.arg, Parameter.VAR_KEYWORD,                                 annotation=annotation))     return_annotation = ast_unparse(node.returns) or Parameter.empty    return_annotation = ast_unparse(node.returns, code) or Parameter.empty      return inspect.Signature(params, return_annotation=return_annotation)


Question: autodoctypehints does not effect to overloaded callables Describe the bug autodoctypehints does not effect to overloaded callables. To Reproduce Expected behavior All typehints for overloaded callables are obeyed setting. Your project No Screenshots No Environment info OS: Mac Python version: 3.8.2 Sphinx version: 3.1.0dev Sphinx extensions: Extra tools: No Additional context No

def format_signature(self, **kwargs: Any) -> str:         sigs = []        if self.analyzer and '.'.join(self.objpath) in self.analyzer.overloads:        if (self.analyzer and                '.'.join(self.objpath) in self.analyzer.overloads and                self.env.config.autodoc_typehints == 'signature'):             # Use signatures for overloaded functions instead of the implementation function.             overloaded = True         else:


Question: autodoctypehints does not effect to overloaded callables Describe the bug autodoctypehints does not effect to overloaded callables. To Reproduce Expected behavior All typehints for overloaded callables are obeyed setting. Your project No Screenshots No Environment info OS: Mac Python version: 3.8.2 Sphinx version: 3.1.0dev Sphinx extensions: Extra tools: No Additional context No

sigs = []          overloads = self.get_overloaded_signatures()        if overloads:        if overloads and self.env.config.autodoc_typehints == 'signature':             # Use signatures for overloaded methods instead of the implementation method.             method = safe_getattr(self._signature_class, self._signature_method_name, None)             __globals__ = safe_getattr(method, '__globals__', {})


Question: autodoctypehints does not effect to overloaded callables Describe the bug autodoctypehints does not effect to overloaded callables. To Reproduce Expected behavior All typehints for overloaded callables are obeyed setting. Your project No Screenshots No Environment info OS: Mac Python version: 3.8.2 Sphinx version: 3.1.0dev Sphinx extensions: Extra tools: No Additional context No

def format_signature(self, **kwargs: Any) -> str:         sigs = []        if self.analyzer and '.'.join(self.objpath) in self.analyzer.overloads:        if (self.analyzer and                '.'.join(self.objpath) in self.analyzer.overloads and                self.env.config.autodoc_typehints == 'signature'):             # Use signatures for overloaded methods instead of the implementation method.             overloaded = True         else:


Question: Generate man page section directories Current man page generation does not conform to search functionality Currently, all generated man pages are placed in to a single-level directory: . Unfortunately, this cannot be used in combination with the unix environment variable. The program explicitly looks for man pages in section directories (such as , etc.). Describe the solution you'd like It would be great if sphinx would automatically create the section directories (e.g., , , etc.) and place each generated man page within appropriate section. Describe alternatives you've considered This problem can be over come within our project’s build system, ensuring the built man pages are installed in a correct location, but it would be nice if the build directory had the proper layout. I’m happy to take a crack at implementing a fix, though this change in behavior may break some people who expect everything to appear in a directory.

app.add_config_value('man_pages', default_man_pages, None)     app.add_config_value('man_show_urls', False, None)    app.add_config_value('man_make_section_directory', False, None)    app.add_config_value('man_make_section_directory', True, None)      return {         'version': 'builtin',


Question: [Napoleon] Retrieve type of attributes from type hints when using google-style Following , I an section my classes docstring. As I have annotations (because I use ), I did not add types in the docstring., as per the style guide. When generating the documentation with from , with , the attributes are not typed. I tried using the flag of , but this resulted in duplicated attributes: one with the explanation, the other with the type-hint. While it is possible to not use type hints with and replace by , this is not an option for e.g. . I also tried , which silenced sphinx's warnings but still resulted in two definition of the attribute in the documentation. It would be nice if (or ) extracted the type hint of the class, or merged the attributes when using . That would avoid duplicated types definitions in either the code or the doc. Currently, either the code has an annotation and a type in the docstring, or the generated documentation has two entry for each attribute. This might be related to and . Additional info sphinx version

def _private_without_docstring(self):         passclass ExamplePEP526Class:    """The summary line for a class docstring should fit on one line.    If the class has public attributes, they may be documented here    in an ``Attributes`` section and follow the same formatting as a    function's ``Args`` section. If ``napoleon_attr_annotations``    is True, types can be specified in the class body using ``PEP 526``    annotations.    Attributes:        attr1: Description of `attr1`.        attr2: Description of `attr2`.    """    attr1: str    attr2: int\ No newline at end of filediff --git a/sphinx/ext/napoleon/__init__.py b/sphinx/ext/napoleon/__init__.py-- a/sphinx/ext/napoleon/__init__.py++ b/sphinx/ext/napoleon/__init__.py


Question: [Napoleon] Retrieve type of attributes from type hints when using google-style Following , I an section my classes docstring. As I have annotations (because I use ), I did not add types in the docstring., as per the style guide. When generating the documentation with from , with , the attributes are not typed. I tried using the flag of , but this resulted in duplicated attributes: one with the explanation, the other with the type-hint. While it is possible to not use type hints with and replace by , this is not an option for e.g. . I also tried , which silenced sphinx's warnings but still resulted in two definition of the attribute in the documentation. It would be nice if (or ) extracted the type hint of the class, or merged the attributes when using . That would avoid duplicated types definitions in either the code or the doc. Currently, either the code has an annotation and a type in the docstring, or the generated documentation has two entry for each attribute. This might be related to and . Additional info sphinx version

napoleon_preprocess_types = False         napoleon_type_aliases = None         napoleon_custom_sections = None<ins>        napoleon_attr_annotations = True</ins>      .. _Google style:        https://google.github.io/styleguide/pyguide.html


Question: [Napoleon] Retrieve type of attributes from type hints when using google-style Following , I an section my classes docstring. As I have annotations (because I use ), I did not add types in the docstring., as per the style guide. When generating the documentation with from , with , the attributes are not typed. I tried using the flag of , but this resulted in duplicated attributes: one with the explanation, the other with the type-hint. While it is possible to not use type hints with and replace by , this is not an option for e.g. . I also tried , which silenced sphinx's warnings but still resulted in two definition of the attribute in the documentation. It would be nice if (or ) extracted the type hint of the class, or merged the attributes when using . That would avoid duplicated types definitions in either the code or the doc. Currently, either the code has an annotation and a type in the docstring, or the generated documentation has two entry for each attribute. This might be related to and . Additional info sphinx version

section. If the entry is a tuple/list/indexed container, the first entry         is the name of the section, the second is the section key to emulate. <ins>    napoleon_attr_annotations : :obj:`bool` (Defaults to True)        Use the type annotations of class attributes that are documented in the docstring        but do not have a type in the docstring.</ins>      """     _config_values = {


Question: [Napoleon] Retrieve type of attributes from type hints when using google-style Following , I an section my classes docstring. As I have annotations (because I use ), I did not add types in the docstring., as per the style guide. When generating the documentation with from , with , the attributes are not typed. I tried using the flag of , but this resulted in duplicated attributes: one with the explanation, the other with the type-hint. While it is possible to not use type hints with and replace by , this is not an option for e.g. . I also tried , which silenced sphinx's warnings but still resulted in two definition of the attribute in the documentation. It would be nice if (or ) extracted the type hint of the class, or merged the attributes when using . That would avoid duplicated types definitions in either the code or the doc. Currently, either the code has an annotation and a type in the docstring, or the generated documentation has two entry for each attribute. This might be related to and . Additional info sphinx version

'napoleon_use_keyword': (True, 'env'),         'napoleon_preprocess_types': (False, 'env'),         'napoleon_type_aliases': (None, 'env'),        'napoleon_custom_sections': (None, 'env')        'napoleon_custom_sections': (None, 'env'),        'napoleon_attr_annotations': (True, 'env'),     }      def __init__(self, **settings: Any) -> None:diff --git a/sphinx/ext/napoleon/docstring.py b/sphinx/ext/napoleon/docstring.py-- a/sphinx/ext/napoleon/docstring.py++ b/sphinx/ext/napoleon/docstring.py


Question: [Napoleon] Retrieve type of attributes from type hints when using google-style Following , I an section my classes docstring. As I have annotations (because I use ), I did not add types in the docstring., as per the style guide. When generating the documentation with from , with , the attributes are not typed. I tried using the flag of , but this resulted in duplicated attributes: one with the explanation, the other with the type-hint. While it is possible to not use type hints with and replace by , this is not an option for e.g. . I also tried , which silenced sphinx's warnings but still resulted in two definition of the attribute in the documentation. It would be nice if (or ) extracted the type hint of the class, or merged the attributes when using . That would avoid duplicated types definitions in either the code or the doc. Currently, either the code has an annotation and a type in the docstring, or the generated documentation has two entry for each attribute. This might be related to and . Additional info sphinx version

from sphinx.ext.napoleon.iterators import modify_iter from sphinx.locale import _, __ from sphinx.util import logging<ins>from sphinx.util.inspect import stringify_annotationfrom sphinx.util.typing import get_type_hints</ins>  if False:     # For type annotation


Question: [Napoleon] Retrieve type of attributes from type hints when using google-style Following , I an section my classes docstring. As I have annotations (because I use ), I did not add types in the docstring., as per the style guide. When generating the documentation with from , with , the attributes are not typed. I tried using the flag of , but this resulted in duplicated attributes: one with the explanation, the other with the type-hint. While it is possible to not use type hints with and replace by , this is not an option for e.g. . I also tried , which silenced sphinx's warnings but still resulted in two definition of the attribute in the documentation. It would be nice if (or ) extracted the type hint of the class, or merged the attributes when using . That would avoid duplicated types definitions in either the code or the doc. Currently, either the code has an annotation and a type in the docstring, or the generated documentation has two entry for each attribute. This might be related to and . Additional info sphinx version

def _parse_attributes_section(self, section: str) -> List[str]:         lines = []         for _name, _type, _desc in self._consume_fields():<ins>            if not _type:                _type = self._lookup_annotation(_name)</ins>             if self._config.napoleon_use_ivar:                 _name = self._qualify_name(_name, self._obj)                 field = ':ivar %s: ' % _name


Question: [Napoleon] Retrieve type of attributes from type hints when using google-style Following , I an section my classes docstring. As I have annotations (because I use ), I did not add types in the docstring., as per the style guide. When generating the documentation with from , with , the attributes are not typed. I tried using the flag of , but this resulted in duplicated attributes: one with the explanation, the other with the type-hint. While it is possible to not use type hints with and replace by , this is not an option for e.g. . I also tried , which silenced sphinx's warnings but still resulted in two definition of the attribute in the documentation. It would be nice if (or ) extracted the type hint of the class, or merged the attributes when using . That would avoid duplicated types definitions in either the code or the doc. Currently, either the code has an annotation and a type in the docstring, or the generated documentation has two entry for each attribute. This might be related to and . Additional info sphinx version

lines = lines[start:end + 1]         return lines <ins>    def _lookup_annotation(self, _name: str) -> str:        if self._config.napoleon_attr_annotations:            if self._what in ("module", "class", "exception") and self._obj:                # cache the class annotations                if not hasattr(self, "_annotations"):                    localns = getattr(self._config, "autodoc_type_aliases", {})                    localns.update(getattr(                                   self._config, "napoleon_type_aliases", {}                                   ) or {})                    self._annotations = get_type_hints(self._obj, None, localns)                if _name in self._annotations:                    return stringify_annotation(self._annotations[_name])        # No annotation found        return ""</ins>  def _recombine_set_tokens(tokens: List[str]) -> List[str]:     token_queue = collections.deque(tokens)


Question: [Napoleon] Retrieve type of attributes from type hints when using google-style Following , I an section my classes docstring. As I have annotations (because I use ), I did not add types in the docstring., as per the style guide. When generating the documentation with from , with , the attributes are not typed. I tried using the flag of , but this resulted in duplicated attributes: one with the explanation, the other with the type-hint. While it is possible to not use type hints with and replace by , this is not an option for e.g. . I also tried , which silenced sphinx's warnings but still resulted in two definition of the attribute in the documentation. It would be nice if (or ) extracted the type hint of the class, or merged the attributes when using . That would avoid duplicated types definitions in either the code or the doc. Currently, either the code has an annotation and a type in the docstring, or the generated documentation has two entry for each attribute. This might be related to and . Additional info sphinx version

_name, _type = _name.strip(), _type.strip()         _name = self._escape_args_and_kwargs(_name)         if parse_type and not _type:            _type = self._lookup_annotation(_name)         if prefer_type and not _type:             _type, _name = _name, _type diff --git a/sphinx/util/typing.py b/sphinx/util/typing.py-- a/sphinx/util/typing.py++ b/sphinx/util/typing.py


Question: [Napoleon] Retrieve type of attributes from type hints when using google-style Following , I an section my classes docstring. As I have annotations (because I use ), I did not add types in the docstring., as per the style guide. When generating the documentation with from , with , the attributes are not typed. I tried using the flag of , but this resulted in duplicated attributes: one with the explanation, the other with the type-hint. While it is possible to not use type hints with and replace by , this is not an option for e.g. . I also tried , which silenced sphinx's warnings but still resulted in two definition of the attribute in the documentation. It would be nice if (or ) extracted the type hint of the class, or merged the attributes when using . That would avoid duplicated types definitions in either the code or the doc. Currently, either the code has an annotation and a type in the docstring, or the generated documentation has two entry for each attribute. This might be related to and . Additional info sphinx version

from sphinx.util.inspect import safe_getattr  # lazy loading      try:        return typing.get_type_hints(obj, None, localns)        return typing.get_type_hints(obj, globalns, localns)     except NameError:         # Failed to evaluate ForwardRef (maybe TYPE_CHECKING)         return safe_getattr(obj, '__annotations__', {})


Question: autodoc uses a wrapper's signature for a decorated class Describe the bug uses a wrapper's signature for a decorated class. To Reproduce Branch: Steps to reproduce the behavior: In , add:. In , add: Then, run: This outputs: Expected behavior A clear and concise description of what you expected to happen. Your project Link to your sphinx project, or attach zipped small project sample. Screenshots If applicable, add screenshots to help explain your problem. Environment info OS: [e.g. Unix/Linux/Mac/Win/other with version] Python version: [e.g. 3.7.1] Sphinx version: [e.g. 1.8.2] Sphinx extensions: [e.g. , recommonmark] Extra tools: [e.g. Browser, tex or something else] Additional context Add any other context about the problem here. [e.g. URL or Ticket]

try:             self.env.app.emit('autodoc-before-process-signature', self.object, False)            sig = inspect.signature(self.object, follow_wrapped=True,            sig = inspect.signature(self.object,                                     type_aliases=self.env.config.autodoc_type_aliases)             args = stringify_signature(sig, **kwargs)         except TypeError as exc:


Question: autodoc uses a wrapper's signature for a decorated class Describe the bug uses a wrapper's signature for a decorated class. To Reproduce Branch: Steps to reproduce the behavior: In , add:. In , add: Then, run: This outputs: Expected behavior A clear and concise description of what you expected to happen. Your project Link to your sphinx project, or attach zipped small project sample. Screenshots If applicable, add screenshots to help explain your problem. Environment info OS: [e.g. Unix/Linux/Mac/Win/other with version] Python version: [e.g. 3.7.1] Sphinx version: [e.g. 1.8.2] Sphinx extensions: [e.g. , recommonmark] Extra tools: [e.g. Browser, tex or something else] Additional context Add any other context about the problem here. [e.g. URL or Ticket]

else:                     self.env.app.emit('autodoc-before-process-signature', self.object, True)                     sig = inspect.signature(self.object, bound_method=True,                                            follow_wrapped=True,                                             type_aliases=self.env.config.autodoc_type_aliases)                 args = stringify_signature(sig, **kwargs)         except TypeError as exc:diff --git a/sphinx/util/inspect.py b/sphinx/util/inspect.py-- a/sphinx/util/inspect.py++ b/sphinx/util/inspect.py


Question: autodoc uses a wrapper's signature for a decorated class Describe the bug uses a wrapper's signature for a decorated class. To Reproduce Branch: Steps to reproduce the behavior: In , add:. In , add: Then, run: This outputs: Expected behavior A clear and concise description of what you expected to happen. Your project Link to your sphinx project, or attach zipped small project sample. Screenshots If applicable, add screenshots to help explain your problem. Environment info OS: [e.g. Unix/Linux/Mac/Win/other with version] Python version: [e.g. 3.7.1] Sphinx version: [e.g. 1.8.2] Sphinx extensions: [e.g. , recommonmark] Extra tools: [e.g. Browser, tex or something else] Additional context Add any other context about the problem here. [e.g. URL or Ticket]

return False  def signature(subject: Callable, bound_method: bool = False, follow_wrapped: bool = False,def signature(subject: Callable, bound_method: bool = False, follow_wrapped: bool = None,               type_aliases: Dict = {}) -> inspect.Signature:     """Return a Signature object for the given *subject*.      :param bound_method: Specify *subject* is a bound method or not     :param follow_wrapped: Same as ``inspect.signature()``.                           Defaults to ``False`` (get a signature of *subject*).     """    if follow_wrapped is None:        follow_wrapped = True    else:        warnings.warn('The follow_wrapped argument of sphinx.util.inspect.signature() is '                      'deprecated', RemovedInSphinx50Warning, stacklevel=2)     try:         try:             if _should_unwrap(subject):


Question: autodoctypealiases does not effect to variables and attributes Describe the bug autodoctypealiases does not effect to variables and attributes To Reproduce Expected behavior should be applied to and . Your project N/A Screenshots N/A Environment info OS: Mac Python version: 3.9.0 Sphinx version: HEAD of 3.x branch Sphinx extensions: Extra tools: Nothing Additional context N/A

if not self.options.annotation:             # obtain annotation for this data             try:                annotations = get_type_hints(self.parent)                annotations = get_type_hints(self.parent, None,                                             self.config.autodoc_type_aliases)             except NameError:                 # Failed to evaluate ForwardRef (maybe TYPE_CHECKING)                 annotations = safe_getattr(self.parent, '__annotations__', {})


Question: autodoctypealiases does not effect to variables and attributes Describe the bug autodoctypealiases does not effect to variables and attributes To Reproduce Expected behavior should be applied to and . Your project N/A Screenshots N/A Environment info OS: Mac Python version: 3.9.0 Sphinx version: HEAD of 3.x branch Sphinx extensions: Extra tools: Nothing Additional context N/A

if not self.options.annotation:             # obtain type annotation for this attribute             try:                annotations = get_type_hints(self.parent)                annotations = get_type_hints(self.parent, None,                                             self.config.autodoc_type_aliases)             except NameError:                 # Failed to evaluate ForwardRef (maybe TYPE_CHECKING)                 annotations = safe_getattr(self.parent, '__annotations__', {})


Question: autodoctypealiases doesn't work when autodoctypehints is set to "description" Describe the bug autodoctypealiases doesn't work when autodoctypehints is set to "description". To Reproduce I get, Then if I remove I get, Expected behavior instead of in both cases. Environment info OS: Mac Catalina 10.15.7 Python version: 3.7.9 Sphinx version: 3.3.1 Sphinx extensions: , ,

if callable(obj):             annotations = app.env.temp_data.setdefault('annotations', {})             annotation = annotations.setdefault(name, OrderedDict())            sig = inspect.signature(obj)            sig = inspect.signature(obj, type_aliases=app.config.autodoc_type_aliases)             for param in sig.parameters.values():                 if param.annotation is not param.empty:                     annotation[param.name] = typing.stringify(param.annotation)


Question: v3.3 upgrade started generating "WARNING: no number is assigned for table" warnings We've updated to Sphinx 3.3 in our documentation, and suddenly the following warning started popping up in our builds when we build either or .: I looked through the changelog but it didn't seem like there was anything related to that was changed, but perhaps I missed something? Could anyone point me to a change in the numref logic so I can figure out where these warnings are coming from?

if fignumber is None:                 return contnode         except ValueError:            logger.warning(__("no number is assigned for %s: %s"), figtype, labelid,                           location=node)            logger.warning(__("Failed to create a cross reference. Any number is not "                              "assigned: %s"),                           labelid, location=node)             return contnode          try:


Question: Extend linkchecker GET fallback logic to handle Too Many Redirects Subject: linkcheck - fallback to GET requests when HEAD requests returns Too Many Redirects Bugfix Some websites will enter infinite redirect loops with HEAD requests. In this case, the GET fallback is ignored as the exception is of type and the link is reported as broken. This extends the except clause to retry with a GET request for such scenarios. Classifying this as a bug fix as URLs like used to pass the linkchecking prior to Sphinx 3.2.0 but are now failing as HEAD requests have been enforced (). /cc

from docutils import nodes from docutils.nodes import Nodefrom requests.exceptions import HTTPErrorfrom requests.exceptions import HTTPError, TooManyRedirects  from sphinx.application import Sphinx from sphinx.builders import Builder


Question: Extend linkchecker GET fallback logic to handle Too Many Redirects Subject: linkcheck - fallback to GET requests when HEAD requests returns Too Many Redirects Bugfix Some websites will enter infinite redirect loops with HEAD requests. In this case, the GET fallback is ignored as the exception is of type and the link is reported as broken. This extends the except clause to retry with a GET request for such scenarios. Classifying this as a bug fix as URLs like used to pass the linkchecking prior to Sphinx 3.2.0 but are now failing as HEAD requests have been enforced (). /cc

config=self.app.config, auth=auth_info,                                                  **kwargs)                         response.raise_for_status()                    except HTTPError:                    except (HTTPError, TooManyRedirects):                         # retry with GET request if that fails, some servers                         # don't like HEAD requests.                         response = requests.get(req_url, stream=True, config=self.app.config,


Question: autoattribute could not create document for slots attributes correctly Describe the bug autoattribute could not create document for slots attributes correctly To Reproduce The build succeeded. But docstring is not shown. Expected behavior Document should be generated successfully like when I used . Your project N/A Screenshots N/A Environment info OS: Mac Python version: 3.9.0 Sphinx version: HEAD of 3.x Sphinx extensions: Extra tools: Nothing Additional context Nothing

class DataDocumenterMixinBase:     # define types of instance variables    parent = None  # type: Any     object = None  # type: Any    objpath = None  # type: List[str]      def should_suppress_directive_header(self) -> bool:         """Check directive header should be suppressed."""


Question: autoattribute could not create document for slots attributes correctly Describe the bug autoattribute could not create document for slots attributes correctly To Reproduce The build succeeded. But docstring is not shown. Expected behavior Document should be generated successfully like when I used . Your project N/A Screenshots N/A Environment info OS: Mac Python version: 3.9.0 Sphinx version: HEAD of 3.x Sphinx extensions: Extra tools: Nothing Additional context Nothing

super().__init__(*args, **kwargs)  class AttributeDocumenter(NewTypeMixin, TypeVarMixin,  # type: ignoreclass SlotsMixin(DataDocumenterMixinBase):    """    Mixin for AttributeDocumenter to provide the feature for supporting __slots__.    """    def isslotsattribute(self) -> bool:        """Check the subject is an attribute in __slots__."""        try:            __slots__ = inspect.getslots(self.parent)            if __slots__ and self.objpath[-1] in __slots__:                return True            else:                return False        except (AttributeError, ValueError):            return False    def import_object(self, raiseerror: bool = False) -> bool:        ret = super().import_object(raiseerror)  # type: ignore        if self.isslotsattribute():            self.object = SLOTSATTR        return ret    def should_suppress_directive_header(self) -> bool:        if self.object is SLOTSATTR:            self._datadescriptor = True            return True        else:            return super().should_suppress_directive_header()    def get_doc(self, encoding: str = None, ignore: int = None) -> List[List[str]]:        if self.object is SLOTSATTR:            try:                __slots__ = inspect.getslots(self.parent)                if __slots__ and __slots__.get(self.objpath[-1]):                    docstring = prepare_docstring(__slots__[self.objpath[-1]])                    return [docstring]                else:                    return []            except (AttributeError, ValueError) as exc:                logger.warning(__('Invalid __slots__ found on %s. Ignored.'),                               (self.parent.__qualname__, exc), type='autodoc')                return []        else:            return super().get_doc(encoding, ignore)  # type: ignoreclass AttributeDocumenter(NewTypeMixin, SlotsMixin, TypeVarMixin,  # type: ignore                           DocstringStripSignatureMixin, ClassLevelDocumenter):     """     Specialized Documenter subclass for attributes.


Question: autoattribute could not create document for slots attributes correctly Describe the bug autoattribute could not create document for slots attributes correctly To Reproduce The build succeeded. But docstring is not shown. Expected behavior Document should be generated successfully like when I used . Your project N/A Screenshots N/A Environment info OS: Mac Python version: 3.9.0 Sphinx version: HEAD of 3.x Sphinx extensions: Extra tools: Nothing Additional context Nothing

# must be higher than AttributeDocumenter     priority = 11     @classmethod    def can_document_member(cls, member: Any, membername: str, isattr: bool, parent: Any                            ) -> bool:        """This documents only SLOTSATTR members."""        return member is SLOTSATTR    def import_object(self, raiseerror: bool = False) -> bool:        """Never import anything."""        # disguise as an attribute        self.objtype = 'attribute'        self._datadescriptor = True        with mock(self.config.autodoc_mock_imports):            try:                ret = import_object(self.modname, self.objpath[:-1], 'class',                                    attrgetter=self.get_attr,                                    warningiserror=self.config.autodoc_warningiserror)                self.module, _, _, self.parent = ret                return True            except ImportError as exc:                if raiseerror:                    raise                else:                    logger.warning(exc.args[0], type='autodoc', subtype='import_object')                    self.env.note_reread()                    return False    def get_doc(self, encoding: str = None, ignore: int = None) -> List[List[str]]:        """Decode and return lines of the docstring(s) for the object."""        if ignore is not None:            warnings.warn("The 'ignore' argument to autodoc.%s.get_doc() is deprecated."                          % self.__class__.__name__,                          RemovedInSphinx50Warning, stacklevel=2)        name = self.objpath[-1]        try:            __slots__ = inspect.getslots(self.parent)            if __slots__ and isinstance(__slots__.get(name, None), str):                docstring = prepare_docstring(__slots__[name])                return [docstring]            else:                return []        except (AttributeError, ValueError) as exc:            logger.warning(__('Invalid __slots__ found on %s. Ignored.'),                           (self.parent.__qualname__, exc), type='autodoc')            return []    def __init__(self, *args: Any, **kwargs: Any) -> None:        warnings.warn("%s is deprecated." % self.__class__.__name__,                      RemovedInSphinx50Warning, stacklevel=2)        super().__init__(*args, **kwargs)   class NewTypeAttributeDocumenter(AttributeDocumenter):


Question: autoattribute could not create document for slots attributes correctly Describe the bug autoattribute could not create document for slots attributes correctly To Reproduce The build succeeded. But docstring is not shown. Expected behavior Document should be generated successfully like when I used . Your project N/A Screenshots N/A Environment info OS: Mac Python version: 3.9.0 Sphinx version: HEAD of 3.x Sphinx extensions: Extra tools: Nothing Additional context Nothing

app.add_autodocumenter(AttributeDocumenter)     app.add_autodocumenter(PropertyDocumenter)     app.add_autodocumenter(InstanceAttributeDocumenter)    app.add_autodocumenter(SlotsAttributeDocumenter)     app.add_autodocumenter(NewTypeAttributeDocumenter)      app.add_config_value('autoclass_content', 'class', True, ENUM('both', 'class', 'init'))diff --git a/sphinx/ext/autosummary/generate.py b/sphinx/ext/autosummary/generate.py-- a/sphinx/ext/autosummary/generate.py++ b/sphinx/ext/autosummary/generate.py


Question: autoattribute could not create document for slots attributes correctly Describe the bug autoattribute could not create document for slots attributes correctly To Reproduce The build succeeded. But docstring is not shown. Expected behavior Document should be generated successfully like when I used . Your project N/A Screenshots N/A Environment info OS: Mac Python version: 3.9.0 Sphinx version: HEAD of 3.x Sphinx extensions: Extra tools: Nothing Additional context Nothing

InstanceAttributeDocumenter, MethodDocumenter,                                     ModuleDocumenter, NewTypeAttributeDocumenter,                                     NewTypeDataDocumenter, PropertyDocumenter,                                    SingledispatchFunctionDocumenter, SlotsAttributeDocumenter)                                    SingledispatchFunctionDocumenter)     documenters = [         ModuleDocumenter, ClassDocumenter, ExceptionDocumenter, DataDocumenter,         FunctionDocumenter, MethodDocumenter, NewTypeAttributeDocumenter,         NewTypeDataDocumenter, AttributeDocumenter, InstanceAttributeDocumenter,        DecoratorDocumenter, PropertyDocumenter, SlotsAttributeDocumenter,        GenericAliasDocumenter, SingledispatchFunctionDocumenter,        DecoratorDocumenter, PropertyDocumenter, GenericAliasDocumenter,        SingledispatchFunctionDocumenter,     ]  # type: List[Type[Documenter]]     for documenter in documenters:         app.registry.add_documenter(documenter.objtype, documenter)


Question: Sphinx 3.2 complains about option:: syntax that earlier versions accepted Sphinx 3.2 complains about use of the option:: directive that earlier versions accepted without complaint. The QEMU documentation includes this: as part of the documentation of the command line options of one of its programs. Earlier versions of Sphinx were fine with this, but Sphinx 3.2 complains: Sphinx ideally shouldn't change in ways that break the building of documentation that worked in older versions, because this makes it unworkably difficult to have documentation that builds with whatever the Linux distro's sphinx-build is. The error message suggests that Sphinx has a very restrictive idea of what option syntax is; it would be better if it just accepted any string, because not all programs and OSes have option syntax that matches the limited list the error message indicates.

# RE for option descriptionsoption_desc_re = re.compile(r'((?:/|--|-|\+)?[^\s=[]+)(=?\s*.*)')option_desc_re = re.compile(r'((?:/|--|-|\+)?[^\s=]+)(=?\s*.*)') # RE for grammar tokens token_re = re.compile(r'`(\w+)`', re.U)


Question: Sphinx 3.2 complains about option:: syntax that earlier versions accepted Sphinx 3.2 complains about use of the option:: directive that earlier versions accepted without complaint. The QEMU documentation includes this: as part of the documentation of the command line options of one of its programs. Earlier versions of Sphinx were fine with this, but Sphinx 3.2 complains: Sphinx ideally shouldn't change in ways that break the building of documentation that worked in older versions, because this makes it unworkably difficult to have documentation that builds with whatever the Linux distro's sphinx-build is. The error message suggests that Sphinx has a very restrictive idea of what option syntax is; it would be better if it just accepted any string, because not all programs and OSes have option syntax that matches the limited list the error message indicates.

location=signode)                 continue             optname, args = m.groups()<ins>            if optname.endswith('[') and args.endswith(']'):                # optional value surrounded by brackets (ex. foo[=bar])                optname = optname[:-1]                args = '[' + args</ins>             if count:                 signode += addnodes.desc_addname(', ', ', ')             signode += addnodes.desc_name(optname, optname)


Question: Use uplatex for default latexengine for Japanese docs Is your feature request related to a problem? Please describe. Use uplatex for default latexengine for Japanese docs. Describe the solution you'd like Since v2.3, Sphinx supports uplatex as an alternative of latexengine for Japanese docs (refs: , ). uplatex is able to build a document without conversion character encoding internally. It allows using unicode characters in documents. Additionally, uplatex is compatible with platex (current default latexengine for Japanese docs). Describe alternatives you've considered Nothing. Additional context Nothing.

def default_latex_engine(config: Config) -> str:     """ Better default latex_engine settings for specific languages. """     if config.language == 'ja':        return 'platex'        return 'uplatex'     elif (config.language or '').startswith('zh'):         return 'xelatex'     elif config.language == 'el':


Question: autodoctypehints='description' does not combine well with autoclasscontent='class' With this configuration: Type hints from the method are reflected in descriptions (given explicitly in the docstrings), and are also generated for the class itself. To Reproduce Expected behavior No "Parameters" section should be to the class docs if already present for the docs simply because of the type hints. Your project Sample attached. Environment info OS: Ubuntu 18.04 Python version: 3.7, 3.8, 3.9 Sphinx version: 2.4.4 autodoctypehints="description" doesn't use init type hints Describe the bug Type hints attached to the method are not used when , but are used when . To Reproduce Create with these contents: Create with these contents: Generate documentation into an directory: Expected behavior The parameter of the constructor should have a type annotation, like the parameter of does. When , the signature does include the type annotation. Adding causes the type hint to be used, but: believe the type hint should be used even for like it is if , and causes a annotation to be , which is not helpful for a constructor and which doesn't match the behavior of (there's no in that case). Environment info OS: Linux Python version: 3.8.5 Sphinx version: 3.2.1 Sphinx extensions: and Additional context This appears to be intentional behavior as it was the fix for , but I believe it is incorrect because it is inconsistent with how signature type hints are handled.

app.add_config_value('autodoc_mock_imports', [], True)     app.add_config_value('autodoc_typehints', "signature", True,                          ENUM("signature", "description", "none"))    app.add_config_value('autodoc_typehints_description_target', 'all', True,                         ENUM('all', 'documented'))     app.add_config_value('autodoc_type_aliases', {}, True)     app.add_config_value('autodoc_warningiserror', True, True)     app.add_config_value('autodoc_inherit_docstrings', True, True)diff --git a/sphinx/ext/autodoc/typehints.py b/sphinx/ext/autodoc/typehints.py-- a/sphinx/ext/autodoc/typehints.py++ b/sphinx/ext/autodoc/typehints.py


Question: autodoctypehints='description' does not combine well with autoclasscontent='class' With this configuration: Type hints from the method are reflected in descriptions (given explicitly in the docstrings), and are also generated for the class itself. To Reproduce Expected behavior No "Parameters" section should be to the class docs if already present for the docs simply because of the type hints. Your project Sample attached. Environment info OS: Ubuntu 18.04 Python version: 3.7, 3.8, 3.9 Sphinx version: 2.4.4 autodoctypehints="description" doesn't use init type hints Describe the bug Type hints attached to the method are not used when , but are used when . To Reproduce Create with these contents: Create with these contents: Generate documentation into an directory: Expected behavior The parameter of the constructor should have a type annotation, like the parameter of does. When , the signature does include the type annotation. Adding causes the type hint to be used, but: believe the type hint should be used even for like it is if , and causes a annotation to be , which is not helpful for a constructor and which doesn't match the behavior of (there's no in that case). Environment info OS: Linux Python version: 3.8.5 Sphinx version: 3.2.1 Sphinx extensions: and Additional context This appears to be intentional behavior as it was the fix for , but I believe it is incorrect because it is inconsistent with how signature type hints are handled.

import re from collections import OrderedDictfrom typing import Any, Dict, Iterable, castfrom typing import Any, Dict, Iterable, Set, cast  from docutils import nodes from docutils.nodes import Element


Question: autodoctypehints='description' does not combine well with autoclasscontent='class' With this configuration: Type hints from the method are reflected in descriptions (given explicitly in the docstrings), and are also generated for the class itself. To Reproduce Expected behavior No "Parameters" section should be to the class docs if already present for the docs simply because of the type hints. Your project Sample attached. Environment info OS: Ubuntu 18.04 Python version: 3.7, 3.8, 3.9 Sphinx version: 2.4.4 autodoctypehints="description" doesn't use init type hints Describe the bug Type hints attached to the method are not used when , but are used when . To Reproduce Create with these contents: Create with these contents: Generate documentation into an directory: Expected behavior The parameter of the constructor should have a type annotation, like the parameter of does. When , the signature does include the type annotation. Adding causes the type hint to be used, but: believe the type hint should be used even for like it is if , and causes a annotation to be , which is not helpful for a constructor and which doesn't match the behavior of (there's no in that case). Environment info OS: Linux Python version: 3.8.5 Sphinx version: 3.2.1 Sphinx extensions: and Additional context This appears to be intentional behavior as it was the fix for , but I believe it is incorrect because it is inconsistent with how signature type hints are handled.

return     if app.config.autodoc_typehints != 'description':         return<del>    if objtype == 'class' and app.config.autoclass_content not in ('init', 'both'):        return</del>      try:         signature = cast(addnodes.desc_signature, contentnode.parent[0])


Question: autodoctypehints='description' does not combine well with autoclasscontent='class' With this configuration: Type hints from the method are reflected in descriptions (given explicitly in the docstrings), and are also generated for the class itself. To Reproduce Expected behavior No "Parameters" section should be to the class docs if already present for the docs simply because of the type hints. Your project Sample attached. Environment info OS: Ubuntu 18.04 Python version: 3.7, 3.8, 3.9 Sphinx version: 2.4.4 autodoctypehints="description" doesn't use init type hints Describe the bug Type hints attached to the method are not used when , but are used when . To Reproduce Create with these contents: Create with these contents: Generate documentation into an directory: Expected behavior The parameter of the constructor should have a type annotation, like the parameter of does. When , the signature does include the type annotation. Adding causes the type hint to be used, but: believe the type hint should be used even for like it is if , and causes a annotation to be , which is not helpful for a constructor and which doesn't match the behavior of (there's no in that case). Environment info OS: Linux Python version: 3.8.5 Sphinx version: 3.2.1 Sphinx extensions: and Additional context This appears to be intentional behavior as it was the fix for , but I believe it is incorrect because it is inconsistent with how signature type hints are handled.

field_lists.append(field_list)          for field_list in field_lists:            modify_field_list(field_list, annotations[fullname])            if app.config.autodoc_typehints_description_target == "all":                modify_field_list(field_list, annotations[fullname])            else:                augment_descriptions_with_types(field_list, annotations[fullname])   def insert_field_list(node: Element) -> nodes.field_list:


Question: autodoctypehints='description' does not combine well with autoclasscontent='class' With this configuration: Type hints from the method are reflected in descriptions (given explicitly in the docstrings), and are also generated for the class itself. To Reproduce Expected behavior No "Parameters" section should be to the class docs if already present for the docs simply because of the type hints. Your project Sample attached. Environment info OS: Ubuntu 18.04 Python version: 3.7, 3.8, 3.9 Sphinx version: 2.4.4 autodoctypehints="description" doesn't use init type hints Describe the bug Type hints attached to the method are not used when , but are used when . To Reproduce Create with these contents: Create with these contents: Generate documentation into an directory: Expected behavior The parameter of the constructor should have a type annotation, like the parameter of does. When , the signature does include the type annotation. Adding causes the type hint to be used, but: believe the type hint should be used even for like it is if , and causes a annotation to be , which is not helpful for a constructor and which doesn't match the behavior of (there's no in that case). Environment info OS: Linux Python version: 3.8.5 Sphinx version: 3.2.1 Sphinx extensions: and Additional context This appears to be intentional behavior as it was the fix for , but I believe it is incorrect because it is inconsistent with how signature type hints are handled.

node += field  <ins>def augment_descriptions_with_types(    node: nodes.field_list,    annotations: Dict[str, str],) -> None:    fields = cast(Iterable[nodes.field], node)    has_description = set()  # type: Set[str]    has_type = set()  # type: Set[str]    for field in fields:        field_name = field[0].astext()        parts = re.split(' +', field_name)        if parts[0] == 'param':            if len(parts) == 2:                # :param xxx:                has_description.add(parts[1])            elif len(parts) > 2:                # :param xxx yyy:                name = ' '.join(parts[2:])                has_description.add(name)                has_type.add(name)        elif parts[0] == 'type':            name = ' '.join(parts[1:])            has_type.add(name)        elif parts[0] == 'return':            has_description.add('return')        elif parts[0] == 'rtype':            has_type.add('return')    # Add 'type' for parameters with a description but no declared type.    for name in annotations:        if name == 'return':            continue        if name in has_description and name not in has_type:            field = nodes.field()            field += nodes.field_name('', 'type ' + name)            field += nodes.field_body('', nodes.paragraph('', annotations[name]))            node += field    # Add 'rtype' if 'return' is present and 'rtype' isn't.    if 'return' in annotations:        if 'return' in has_description and 'return' not in has_type:            field = nodes.field()            field += nodes.field_name('', 'rtype')            field += nodes.field_body('', nodes.paragraph('', annotations['return']))            node += field</ins> def setup(app: Sphinx) -> Dict[str, Any]:     app.connect('autodoc-process-signature', record_typehints)     app.connect('object-description-transform', merge_typehints)


Question: autodoc inherited-members won't work for inherited attributes (data members). autodoc searches for a cached docstring using (namespace, attrname) as search-key, but doesn't check for baseclass-namespace. Bitbucket: Originally reported by: Anonymous Originally created at: 2011-08-02T17:05:58.754

self.add_line('   ' + _('Bases: %s') % ', '.join(bases), sourcename)      def get_object_members(self, want_all: bool) -> Tuple[bool, ObjectMembers]:        members = get_class_members(self.object, self.objpath, self.get_attr, self.analyzer)        members = get_class_members(self.object, self.objpath, self.get_attr)         if not want_all:             if not self.options.members:                 return False, []  # type: ignorediff --git a/sphinx/ext/autodoc/importer.py b/sphinx/ext/autodoc/importer.py-- a/sphinx/ext/autodoc/importer.py++ b/sphinx/ext/autodoc/importer.py


Question: autodoc inherited-members won't work for inherited attributes (data members). autodoc searches for a cached docstring using (namespace, attrname) as search-key, but doesn't check for baseclass-namespace. Bitbucket: Originally reported by: Anonymous Originally created at: 2011-08-02T17:05:58.754

from typing import Any, Callable, Dict, List, Mapping, NamedTuple, Optional, Tuple  from sphinx.deprecation import RemovedInSphinx40Warning, deprecated_aliasfrom sphinx.pycode import ModuleAnalyzerfrom sphinx.pycode import ModuleAnalyzer, PycodeError from sphinx.util import logging from sphinx.util.inspect import (getannotations, getmro, getslots, isclass, isenumclass,                                  safe_getattr)


Question: autodoc inherited-members won't work for inherited attributes (data members). autodoc searches for a cached docstring using (namespace, attrname) as search-key, but doesn't check for baseclass-namespace. Bitbucket: Originally reported by: Anonymous Originally created at: 2011-08-02T17:05:58.754

self.docstring = docstring  def get_class_members(subject: Any, objpath: List[str], attrgetter: Callable,                      analyzer: ModuleAnalyzer = None) -> Dict[str, ClassAttribute]:def get_class_members(subject: Any, objpath: List[str], attrgetter: Callable                      ) -> Dict[str, ClassAttribute]:     """Get members and attributes of target class."""     from sphinx.ext.autodoc import INSTANCEATTR


Question: autodoc inherited-members won't work for inherited attributes (data members). autodoc searches for a cached docstring using (namespace, attrname) as search-key, but doesn't check for baseclass-namespace. Bitbucket: Originally reported by: Anonymous Originally created at: 2011-08-02T17:05:58.754

except AttributeError:             continue     # annotation only member (ex. attr: int)    for cls in getmro(subject):        try:            for name in getannotations(cls):                name = unmangle(cls, name)                if name and name not in members:                    members[name] = ClassAttribute(cls, name, INSTANCEATTR)        except AttributeError:            pass    if analyzer:        # append instance attributes (cf. self.attr1) if analyzer knows        namespace = '.'.join(objpath)        for (ns, name), docstring in analyzer.attr_docs.items():            if namespace == ns and name not in members:                members[name] = ClassAttribute(subject, name, INSTANCEATTR,                                               '\n'.join(docstring))    try:        for cls in getmro(subject):            # annotation only member (ex. attr: int)            try:                for name in getannotations(cls):                    name = unmangle(cls, name)                    if name and name not in members:                        members[name] = ClassAttribute(cls, name, INSTANCEATTR)            except AttributeError:                pass            # append instance attributes (cf. self.attr1) if analyzer knows            try:                modname = safe_getattr(cls, '__module__')                qualname = safe_getattr(cls, '__qualname__')                analyzer = ModuleAnalyzer.for_module(modname)                analyzer.analyze()                for (ns, name), docstring in analyzer.attr_docs.items():                    if ns == qualname and name not in members:                        members[name] = ClassAttribute(cls, name, INSTANCEATTR,                                                       '\n'.join(docstring))            except (AttributeError, PycodeError):                pass    except AttributeError:        pass      return members


Question: :type: and :rtype: gives false ambiguous class lookup warnings Describe the bug The implicit xrefs created by the info fields seems to do lookup differently than explicit xref roles. For unqualified names it seems like they search for the name in every (sub)module instead of in the current module and then parent modules. To Reproduce gives the warnings which refer to the 4 unqualified type names. The . Expected behavior No warnings, and the two mentioned types should resolve to. Environment info Sphinx version: tested both with v3.3 and with master

result = super().make_xref(rolename, domain, target,  # type: ignore                                    innernode, contnode, env)         result['refspecific'] = True        result['py:module'] = env.ref_context.get('py:module')        result['py:class'] = env.ref_context.get('py:class')         if target.startswith(('.', '~')):             prefix, result['reftarget'] = target[0], target[1:]             if prefix == '.':diff --git a/sphinx/util/docfields.py b/sphinx/util/docfields.py-- a/sphinx/util/docfields.py++ b/sphinx/util/docfields.py


Question: :type: and :rtype: gives false ambiguous class lookup warnings Describe the bug The implicit xrefs created by the info fields seems to do lookup differently than explicit xref roles. For unqualified names it seems like they search for the name in every (sub)module instead of in the current module and then parent modules. To Reproduce gives the warnings which refer to the 4 unqualified type names. The . Expected behavior No warnings, and the two mentioned types should resolve to. Environment info Sphinx version: tested both with v3.3 and with master

self.directive.domain,                         target,                         contnode=content[0],<ins>                        env=self.directive.state.document.settings.env</ins>                     )                     if _is_single_paragraph(field_body):                         paragraph = cast(nodes.paragraph, field_body[0])


Question: Napoleon: Support NumpyDoc "Receives" docstring section Support the "Receives" section of NumpyDoc guidelines; it is related to Yields, which is already supported. Receives Explanation of parameters passed to a generator’s .send() method, formatted as for Parameters, above. Since, like for Yields and Returns, a single object is always passed to the method, this may describe either the single parameter, or positional arguments passed as a tuple. If a docstring includes Receives it must also include Yields.

'notes': self._parse_notes_section,                 'other parameters': self._parse_other_parameters_section,                 'parameters': self._parse_parameters_section,<ins>                'receive': self._parse_receives_section,                'receives': self._parse_receives_section,</ins>                 'return': self._parse_returns_section,                 'returns': self._parse_returns_section,                 'raise': self._parse_raises_section,


Question: Napoleon: Support NumpyDoc "Receives" docstring section Support the "Receives" section of NumpyDoc guidelines; it is related to Yields, which is already supported. Receives Explanation of parameters passed to a generator’s .send() method, formatted as for Parameters, above. Since, like for Yields and Returns, a single object is always passed to the method, this may describe either the single parameter, or positional arguments passed as a tuple. If a docstring includes Receives it must also include Yields.

lines.append('')         return lines <ins>    def _parse_receives_section(self, section: str) -> List[str]:        if self._config.napoleon_use_param:            # Allow to declare multiple parameters at once (ex: x, y: int)            fields = self._consume_fields(multiple=True)            return self._format_docutils_params(fields)        else:            fields = self._consume_fields()            return self._format_fields(_('Receives'), fields)</ins>     def _parse_references_section(self, section: str) -> List[str]:         use_admonition = self._config.napoleon_use_admonition_for_references         return self._parse_generic_section(_('References'), use_admonition)


Question: Linkcheck crashes in 3.4.0 Describe the bug When running linkcheck in Weblate docs, it crashes with: To Reproduce Steps to reproduce the behavior: Expected behavior No crash :-) Your project Screenshots CI failure: Environment info OS: Linux Python version: 3.8.6 Sphinx version: 3.4.0 Sphinx extensions: several, but should not be relevant here Extra tools: none involved Additional context Add any other context about the problem here. [e.g. URL or Ticket]

from urllib.parse import unquote, urlparse  from docutils import nodesfrom docutils.nodes import Nodefrom docutils.nodes import Element, Node from requests import Response from requests.exceptions import HTTPError, TooManyRedirects


Question: Linkcheck crashes in 3.4.0 Describe the bug When running linkcheck in Weblate docs, it crashes with: To Reproduce Steps to reproduce the behavior: Expected behavior No crash :-) Your project Screenshots CI failure: Environment info OS: Linux Python version: 3.8.6 Sphinx version: 3.4.0 Sphinx extensions: several, but should not be relevant here Extra tools: none involved Additional context Add any other context about the problem here. [e.g. URL or Ticket]

DEFAULT_DELAY = 60.0  <ins>def node_line_or_0(node: Element) -> int:    """    PriorityQueue items must be comparable. The line number is part of the    tuple used by the PriorityQueue, keep an homogeneous type for comparison.    """    return get_node_line(node) or 0</ins> class AnchorCheckParser(HTMLParser):     """Specialized HTML parser that looks for a specific anchor."""


Question: Linkcheck crashes in 3.4.0 Describe the bug When running linkcheck in Weblate docs, it crashes with: To Reproduce Steps to reproduce the behavior: Expected behavior No crash :-) Your project Screenshots CI failure: Environment info OS: Linux Python version: 3.8.6 Sphinx version: 3.4.0 Sphinx extensions: several, but should not be relevant here Extra tools: none involved Additional context Add any other context about the problem here. [e.g. URL or Ticket]

if 'refuri' not in refnode:                 continue             uri = refnode['refuri']            lineno = get_node_line(refnode)            lineno = node_line_or_0(refnode)             uri_info = (CHECK_IMMEDIATELY, uri, docname, lineno)             self.wqueue.put(uri_info, False)             n += 1


Question: Linkcheck crashes in 3.4.0 Describe the bug When running linkcheck in Weblate docs, it crashes with: To Reproduce Steps to reproduce the behavior: Expected behavior No crash :-) Your project Screenshots CI failure: Environment info OS: Linux Python version: 3.8.6 Sphinx version: 3.4.0 Sphinx extensions: several, but should not be relevant here Extra tools: none involved Additional context Add any other context about the problem here. [e.g. URL or Ticket]

for imgnode in doctree.traverse(nodes.image):             uri = imgnode['candidates'].get('?')             if uri and '://' in uri:                lineno = get_node_line(imgnode)                lineno = node_line_or_0(imgnode)                 uri_info = (CHECK_IMMEDIATELY, uri, docname, lineno)                 self.wqueue.put(uri_info, False)                 n += 1


Question: autodoc: does not effect to variables Describe the bug autodoc: does not effect to variables. To Reproduce I expect is shown on the built document, but not shown. Expected behavior should be shown on the built document. Your project No Screenshots No Environment info OS: Mac Python version: 3.9.1 Sphinx version: HEAD of 3.x Sphinx extensions: Extra tools: No Additional context No

from sphinx.deprecation import (RemovedInSphinx40Warning, RemovedInSphinx50Warning,                                 RemovedInSphinx60Warning) from sphinx.environment import BuildEnvironmentfrom sphinx.ext.autodoc.importer import (ClassAttribute, get_class_members, get_module_members,                                         get_object_members, import_module, import_object)from sphinx.ext.autodoc.importer import (ClassAttribute, get_class_members, get_object_members,                                         import_module, import_object) from sphinx.ext.autodoc.mock import mock from sphinx.locale import _, __ from sphinx.pycode import ModuleAnalyzer, PycodeError


Question: autodoc: does not effect to variables Describe the bug autodoc: does not effect to variables. To Reproduce I expect is shown on the built document, but not shown. Expected behavior should be shown on the built document. Your project No Screenshots No Environment info OS: Mac Python version: 3.9.1 Sphinx version: HEAD of 3.x Sphinx extensions: Extra tools: No Additional context No

if self.options.deprecated:             self.add_line('   :deprecated:', sourcename)     def get_module_members(self) -> Dict[str, ObjectMember]:        """Get members of target module."""        if self.analyzer:            attr_docs = self.analyzer.attr_docs        else:            attr_docs = {}        members = {}  # type: Dict[str, ObjectMember]        for name in dir(self.object):            try:                value = safe_getattr(self.object, name, None)                docstring = attr_docs.get(('', name), [])                members[name] = ObjectMember(name, value, docstring="\n".join(docstring))            except AttributeError:                continue        # annotation only member (ex. attr: int)        try:            for name in inspect.getannotations(self.object):                if name not in members:                    docstring = attr_docs.get(('', name), [])                    members[name] = ObjectMember(name, INSTANCEATTR,                                                 docstring="\n".join(docstring))        except AttributeError:            pass        return members     def get_object_members(self, want_all: bool) -> Tuple[bool, ObjectMembers]:        members = self.get_module_members()         if want_all:            members = get_module_members(self.object)             if not self.__all__:                 # for implicit module members, check __module__ to avoid                 # documenting imported objects                return True, members                return True, list(members.values())             else:                ret = []                for name, value in members:                    if name in self.__all__:                        ret.append(ObjectMember(name, value))                    else:                        ret.append(ObjectMember(name, value, skipped=True))                for member in members.values():                    if member.__name__ not in self.__all__:                        member.skipped = True                 return False, ret                return False, list(members.values())         else:             memberlist = self.options.members or []             ret = []             for name in memberlist:                try:                    value = safe_getattr(self.object, name)                    ret.append(ObjectMember(name, value))                except AttributeError:                if name in members:                    ret.append(members[name])                else:                     logger.warning(__('missing attribute mentioned in :members: option: '                                       'module %s, attribute %s') %                                    (safe_getattr(self.object, '__name__', '???'), name),diff --git a/sphinx/ext/autodoc/importer.py b/sphinx/ext/autodoc/importer.py-- a/sphinx/ext/autodoc/importer.py++ b/sphinx/ext/autodoc/importer.py


Question: autodoc: does not effect to variables Describe the bug autodoc: does not effect to variables. To Reproduce I expect is shown on the built document, but not shown. Expected behavior should be shown on the built document. Your project No Screenshots No Environment info OS: Mac Python version: 3.9.1 Sphinx version: HEAD of 3.x Sphinx extensions: Extra tools: No Additional context No

import warnings from typing import Any, Callable, Dict, List, Mapping, NamedTuple, Optional, Tuple from sphinx.deprecation import RemovedInSphinx40Warning, deprecated_aliasfrom sphinx.deprecation import (RemovedInSphinx40Warning, RemovedInSphinx50Warning,                                deprecated_alias) from sphinx.pycode import ModuleAnalyzer, PycodeError from sphinx.util import logging from sphinx.util.inspect import (getannotations, getmro, getslots, isclass, isenumclass,


Question: autodoc: does not effect to variables Describe the bug autodoc: does not effect to variables. To Reproduce I expect is shown on the built document, but not shown. Expected behavior should be shown on the built document. Your project No Screenshots No Environment info OS: Mac Python version: 3.9.1 Sphinx version: HEAD of 3.x Sphinx extensions: Extra tools: No Additional context No

"""Get members of target module."""     from sphinx.ext.autodoc import INSTANCEATTR <ins>    warnings.warn('sphinx.ext.autodoc.importer.get_module_members() is deprecated.',                  RemovedInSphinx50Warning)</ins>     members = {}  # type: Dict[str, Tuple[str, Any]]     for name in dir(module):         try:


Question: autodoc: empty all attribute is ignored Describe the bug autodoc: empty attribute is ignored To Reproduce All foo, bar, and baz are shown. Expected behavior No entries should be shown because is empty. Your project No Screenshots No Environment info OS: Mac Python version: 3.9.1 Sphinx version: HEAD of 3.x Sphinx extensions: Extra tools: No Additional context No

def get_object_members(self, want_all: bool) -> Tuple[bool, ObjectMembers]:         members = self.get_module_members()         if want_all:            if not self.__all__:            if self.__all__ is None:                 # for implicit module members, check __module__ to avoid                 # documenting imported objects                 return True, list(members.values())


Question: Attribute undocumented error for an inherited attribute Describe the bug Sphinx complains about missing documentation for an attribute of an inherited class ( is an attribute of , inherits from ). This showed up with Sphinx 3.4.0 and continues with 3.4.1. I thought this might have been the same issue as , but it has not resolved. To Reproduce Steps to reproduce the behavior: <details<summaryFull session</summary</detailsExpected behavior I expected no warnings/errors since the attribute is only inherited. Your project Screenshots n/a Environment info OS: Ubuntu Linux Python version: CPython 3.8 and 3.9 (others untested) Sphinx version: 3.4.0 and 3.4.1, was ok for <3.4 Sphinx extensions: "", "", "", "", "", "sphinxautodoctypehints", "sphinxqtdocumentation", "sphinxcontribtrio", Extra tools: n/a Additional context n/a

and :value: header will be suppressed unexpectedly.     """     def import_object(self, raiseerror: bool = False) -> bool:        ret = super().import_object(raiseerror)  # type: ignore        if ret and not inspect.isattributedescriptor(self.object):            self.non_data_descriptor = True        else:            self.non_data_descriptor = False        return ret     def should_suppress_value_header(self) -> bool:        return (inspect.isattributedescriptor(self.object) or        return (not getattr(self, 'non_data_descriptor', False) or                 super().should_suppress_directive_header())      def get_doc(self, encoding: str = None, ignore: int = None) -> List[List[str]]:        if not inspect.isattributedescriptor(self.object):        if getattr(self, 'non_data_descriptor', False):             # the docstring of non datadescriptor is very probably the wrong thing             # to display             return []         else:             return super().get_doc(encoding, ignore)  # type: ignore     def add_content(self, more_content: Optional[StringList], no_docstring: bool = False                    ) -> None:        if getattr(self, 'non_data_descriptor', False):            # the docstring of non datadescriptor is very probably the wrong thing            # to display            no_docstring = True        super().add_content(more_content, no_docstring=no_docstring)  # type: ignore  class SlotsMixin(DataDocumenterMixinBase):     """


Question: kbd role generates HTML that's difficult/impossible to style for compound-keystrokes Describe the bug The role doesn't mark container elements with a CSS class, so they can be styled differently that child elements representing actual keystrokes. To Reproduce For the below input the following output is generated: Now we have a problem here: there is no way to differentiate between the parent container element and the child element with CSS selectors! If we provide a CSS style to draw a border around a element, so single keystrokes are displayed correctly, then in the second example we'd get a double border (borders around the child elements, and another border around the parent element). If you want to have borders around single keystrokes, and only around the child elements in compound keystrokes, as shown on the screenshot below, the only way is to differentiate the container and child elements with a CSS class. ! Expected behavior Single keystrokes are fine as they are, no change needed: For compound keystrokes, the container element should be marked with a CSS class (e.g. ) so it can be styled differently than the child elements: Environment info OS: Windows Python version: 3.9.1 Sphinx version: 3.4.0 Sphinx extensions: - Extra tools: -

After::         <literal class="kbd">        <literal class="kbd compound">             <literal class="kbd">                 Control             -


Question: kbd role generates HTML that's difficult/impossible to style for compound-keystrokes Describe the bug The role doesn't mark container elements with a CSS class, so they can be styled differently that child elements representing actual keystrokes. To Reproduce For the below input the following output is generated: Now we have a problem here: there is no way to differentiate between the parent container element and the child element with CSS selectors! If we provide a CSS style to draw a border around a element, so single keystrokes are displayed correctly, then in the second example we'd get a double border (borders around the child elements, and another border around the parent element). If you want to have borders around single keystrokes, and only around the child elements in compound keystrokes, as shown on the screenshot below, the only way is to differentiate the container and child elements with a CSS class. ! Expected behavior Single keystrokes are fine as they are, no change needed: For compound keystrokes, the container element should be marked with a CSS class (e.g. ) so it can be styled differently than the child elements: Environment info OS: Windows Python version: 3.9.1 Sphinx version: 3.4.0 Sphinx extensions: - Extra tools: -

if len(parts) == 1:                 continue <ins>            node['classes'].append('compound')</ins>             node.pop()             while parts:                 key = parts.pop(0)


Question: kbd role produces incorrect HTML when compound-key separators (-, + or ^) are used as keystrokes Describe the bug The role produces incorrect HTML when: 1) defining standalone keystrokes that use any of the compound-key separators (, and ) 2) defining compound keystrokes where one or more keystrokes use any of the compound-key separators (, and ) To Reproduce For the below three keyboard definitions: The following three incorrect output is generated: (1) is treated as a separator with two "blank" keystrokes around it. (2) is treated as a separator with two "blank" keystrokes around it. (3) is treated as a separator within a compound-keystroke, with two "blank" keystrokes around it. Expected behavior For single keystrokes that use , or, just a single element should be created. For compound-keystrokes, the algorithm should differentiate between , and characters appearing in separator vs keystroke positions (currently, it's very simplistic, it just treats all these characters as separators using a simple regexp). Screenshot ! Environment info OS: Windows Python version: 3.9.1 Sphinx version: 3.4.0 Sphinx extensions: - Extra tools: -

"""     default_priority = 400     builders = ('html',)    pattern = re.compile(r'(-|\+|\^|\s+)')    pattern = re.compile(r'(?<=.)(-|\+|\^|\s+)(?=.)')      def run(self, **kwargs: Any) -> None:         matcher = NodeMatcher(nodes.literal, classes=["kbd"])


Question: autodoc isn't able to resolve struct.Struct type annotations Describe the bug If is declared in any type annotations, I get To Reproduce Simple Simple Command line: Expected behavior If you comment out the 2 functions that have type annotations, you'll see that resolves fine and shows up in the resulting documentation. I'd expect that would also resolve correctly. Your project n/a Screenshots n/a Environment info OS: Ubuntu 18.04, 20.04 Python version: 3.8.2 Sphinx version: 3.2.1 Sphinx extensions: '', '', '', '', '' Extra tools: Additional context [e.g. URL or Ticket]

import sys import typing<ins>from struct import Struct</ins> from typing import Any, Callable, Dict, Generator, List, Optional, Tuple, TypeVar, Union  from docutils import nodes


Question: autodoc isn't able to resolve struct.Struct type annotations Describe the bug If is declared in any type annotations, I get To Reproduce Simple Simple Command line: Expected behavior If you comment out the 2 functions that have type annotations, you'll see that resolves fine and shows up in the resulting documentation. I'd expect that would also resolve correctly. Your project n/a Screenshots n/a Environment info OS: Ubuntu 18.04, 20.04 Python version: 3.8.2 Sphinx version: 3.2.1 Sphinx extensions: '', '', '', '', '' Extra tools: Additional context [e.g. URL or Ticket]

return ':obj:`None`'     elif cls is Ellipsis:         return '...'<ins>    elif cls is Struct:        # Before Python 3.9, struct.Struct class has incorrect __module__.        return ':class:`struct.Struct`'</ins>     elif inspect.isNewType(cls):         return ':class:`%s`' % cls.__name__     elif cls.__module__ in ('__builtin__', 'builtins'):


Question: autodoc isn't able to resolve struct.Struct type annotations Describe the bug If is declared in any type annotations, I get To Reproduce Simple Simple Command line: Expected behavior If you comment out the 2 functions that have type annotations, you'll see that resolves fine and shows up in the resulting documentation. I'd expect that would also resolve correctly. Your project n/a Screenshots n/a Environment info OS: Ubuntu 18.04, 20.04 Python version: 3.8.2 Sphinx version: 3.2.1 Sphinx extensions: '', '', '', '', '' Extra tools: Additional context [e.g. URL or Ticket]

return annotation.__qualname__     elif annotation is Ellipsis:         return '...'<ins>    elif annotation is Struct:        # Before Python 3.9, struct.Struct class has incorrect __module__.        return 'struct.Struct'</ins>      if sys.version_info >= (3, 7):  # py37+         return _stringify_py37(annotation)


Question: building psf/requests documentation fails with AttributeError: 'LookupDict' object has no attribute 'name' Describe the bug Since sphinx 3.4.1 building documentation fails with the following: Attached the full log: The issue is not reproducible using sphinx 3.3.1. To Reproduce In addiction to build requests' documentation I managed to reproduce the issue in the interactive python console using the following: I'm able to reproduce the issue in a clean virtualenv with only requests and sphinx installed. Thanks!

valid_names.extend(cls.__name__ for cls in self.object.__mro__)          docstrings = self.get_doc()<ins>        if docstrings is None:            return None, None</ins>         self._new_docstrings = docstrings[:]         self._signatures = []         result = None


Question: building psf/requests documentation fails with AttributeError: 'LookupDict' object has no attribute 'name' Describe the bug Since sphinx 3.4.1 building documentation fails with the following: Attached the full log: The issue is not reproducible using sphinx 3.3.1. To Reproduce In addiction to build requests' documentation I managed to reproduce the issue in the interactive python console using the following: I'm able to reproduce the issue in a clean virtualenv with only requests and sphinx installed. Thanks!

def add_content(self, more_content: Optional[StringList], no_docstring: bool = False                     ) -> None:         if self.doc_as_attr:            more_content = StringList([_('alias of %s') % restify(self.object)], source='')            try:                more_content = StringList([_('alias of %s') % restify(self.object)], source='')            except AttributeError:                pass  # Invalid class object is passed.          super().add_content(more_content)


Question: building psf/requests documentation fails with AttributeError: 'LookupDict' object has no attribute 'name' Describe the bug Since sphinx 3.4.1 building documentation fails with the following: Attached the full log: The issue is not reproducible using sphinx 3.3.1. To Reproduce In addiction to build requests' documentation I managed to reproduce the issue in the interactive python console using the following: I'm able to reproduce the issue in a clean virtualenv with only requests and sphinx installed. Thanks!

and :value: header will be suppressed unexpectedly.     """     def import_object(self, raiseerror: bool = False) -> bool:        ret = super().import_object(raiseerror)  # type: ignore        if ret and not inspect.isattributedescriptor(self.object):            self.non_data_descriptor = True        else:            self.non_data_descriptor = False        return ret     def should_suppress_value_header(self) -> bool:        return (inspect.isattributedescriptor(self.object) or        return (not getattr(self, 'non_data_descriptor', False) or                 super().should_suppress_directive_header())      def get_doc(self, encoding: str = None, ignore: int = None) -> Optional[List[List[str]]]:        if not inspect.isattributedescriptor(self.object):        if getattr(self, 'non_data_descriptor', False):             # the docstring of non datadescriptor is very probably the wrong thing             # to display            return []            return None         else:             return super().get_doc(encoding, ignore)  # type: ignore


Question: building psf/requests documentation fails with AttributeError: 'LookupDict' object has no attribute 'name' Describe the bug Since sphinx 3.4.1 building documentation fails with the following: Attached the full log: The issue is not reproducible using sphinx 3.3.1. To Reproduce In addiction to build requests' documentation I managed to reproduce the issue in the interactive python console using the following: I'm able to reproduce the issue in a clean virtualenv with only requests and sphinx installed. Thanks!

return (self.object is UNINITIALIZED_ATTR or                 super().should_suppress_value_header()) <ins>    def get_doc(self, encoding: str = None, ignore: int = None) -> Optional[List[List[str]]]:        if self.object is UNINITIALIZED_ATTR:            return None        else:            return super().get_doc(encoding, ignore)  # type: ignore</ins>  class AttributeDocumenter(GenericAliasMixin, NewTypeMixin, SlotsMixin,  # type: ignore                           TypeVarMixin, RuntimeInstanceAttributeMixin,


Question: building psf/requests documentation fails with AttributeError: 'LookupDict' object has no attribute 'name' Describe the bug Since sphinx 3.4.1 building documentation fails with the following: Attached the full log: The issue is not reproducible using sphinx 3.3.1. To Reproduce In addiction to build requests' documentation I managed to reproduce the issue in the interactive python console using the following: I'm able to reproduce the issue in a clean virtualenv with only requests and sphinx installed. Thanks!

return True         else:             doc = self.get_doc()            metadata = extract_metadata('\n'.join(sum(doc, [])))            if 'hide-value' in metadata:                return True            if doc:                metadata = extract_metadata('\n'.join(sum(doc, [])))                if 'hide-value' in metadata:                    return True          return False


Question: Instance variables link to other variables of the same name in the project Describe the bug Assume autodoc is used via apidoc. In theory other combinations of autodoc (or maybe even without it) can cause this to occur, but this would be the most common occurrence. If a global variable (or really, any kind of variable, just that this would be the most common occurrence) exists, and inside a class you decide to document a variable of the same name, the document of the instance variable will link to the other occurence of a variable under the same name. This can even occur across subpackages and even across other classes of those subpackages (although this appears to occur less often and seemingly...randomly? This only occurs sometimes (presumably due to the referencing heuristic?)). This is a problem, because, for example, could be and usually is completely unrelated to . Furthermore, (instance variable) could be completely unrelated to (global variable). Of course this latter example is far less likely, but the autolinking of these two together, is strange. To Reproduce Steps to reproduce the behavior: then open 127.0.0.1:8008 in a browser Expected behavior That the class variable documentation not be linked to any other. It is unreasonable to expect these to be in any way related whatsoever. If they happen to be, the user can decide to document it as such with a simple reference to the other variable, such as "see :const:\". There is no reason that a variable on some class of some database-oriented subpackage autolink to the variable on some class of some config-related subpackage (this is what occurred in my codebase, which is private at least while in development. I cannot provide anything except a heavily censored screenshot, as I do not know of a way to trick the referencing heuristic to cause a link to occur in an demo repo). Your project Screenshots Not really applicable because this is example independent but here you go anyway: ! Environment info OS: Ubuntu 14.04.5 (probably irrelevant) Python version: 2.7.6 (probably irrelevant) Sphinx version: 1.8.3 Sphinx extensions: autodoc, intersphinx, and other (probably irrelevant) extensions (todo, viewcode, githubpages in the demo repo, among others in the private repo) Extra tools: Any Browser, sphinx-apidoc

'keyword', 'kwarg', 'kwparam'),                      typerolename='class', typenames=('paramtype', 'type'),                      can_collapse=True),        PyTypedField('variable', label=_('Variables'), rolename='obj',        PyTypedField('variable', label=_('Variables'),                      names=('var', 'ivar', 'cvar'),                      typerolename='class', typenames=('vartype',),                      can_collapse=True),


Question: Napoleon: more custom docstring section styles Although the option help renders custom docstring section, the style is inconsistent with the rest of the doc. For example, I have a custom docstring section . I would like it to be displayed as or docstring section. However, option rendesr in a different style shown in the following picture. ! It will be really helpful if we can customize the custom sections a bit more. The following setting has a similar effect, but it renders the Parameters name instead of the custom name. I would like to do something like the following so that my Custom section has the same style as the Parameter section, and it still keeps my custom name: or The following link includes more details about the solutions: Others people have expressed a similar desire (see sphinx-contrib/napoleon) If you are interested, I would like to provide a PR for this. Thanks!

* To create a custom "generic" section, just pass a string.           * To create an alias for an existing section, pass a tuple containing the             alias name and the original, in that order.          * To create a custom section that displays like the parameters or returns            section, pass a tuple containing the custom section name and a string            value, "params_style" or "returns_style".          If an entry is just a string, it is interpreted as a header for a generic         section. If the entry is a tuple/list/indexed container, the first entry        is the name of the section, the second is the section key to emulate.        is the name of the section, the second is the section key to emulate. If the        second entry value is "params_style" or "returns_style", the custom section        will be displayed like the parameters section or returns section.      napoleon_attr_annotations : :obj:`bool` (Defaults to True)         Use the type annotations of class attributes that are documented in the docstringdiff --git a/sphinx/ext/napoleon/docstring.py b/sphinx/ext/napoleon/docstring.py-- a/sphinx/ext/napoleon/docstring.py++ b/sphinx/ext/napoleon/docstring.py


Question: Napoleon: more custom docstring section styles Although the option help renders custom docstring section, the style is inconsistent with the rest of the doc. For example, I have a custom docstring section . I would like it to be displayed as or docstring section. However, option rendesr in a different style shown in the following picture. ! It will be really helpful if we can customize the custom sections a bit more. The following setting has a similar effect, but it renders the Parameters name instead of the custom name. I would like to do something like the following so that my Custom section has the same style as the Parameter section, and it still keeps my custom name: or The following link includes more details about the solutions: Others people have expressed a similar desire (see sphinx-contrib/napoleon) If you are interested, I would like to provide a PR for this. Thanks!

self._sections[entry.lower()] = self._parse_custom_generic_section                 else:                     # otherwise, assume entry is container;                    # [0] is new section, [1] is the section to alias.                    # in the case of key mismatch, just handle as generic section.                    self._sections[entry[0].lower()] = \                        self._sections.get(entry[1].lower(),                                           self._parse_custom_generic_section)                    if entry[1] == "params_style":                        self._sections[entry[0].lower()] = \                            self._parse_custom_params_style_section                    elif entry[1] == "returns_style":                        self._sections[entry[0].lower()] = \                            self._parse_custom_returns_style_section                    else:                        # [0] is new section, [1] is the section to alias.                        # in the case of key mismatch, just handle as generic section.                        self._sections[entry[0].lower()] = \                            self._sections.get(entry[1].lower(),                                               self._parse_custom_generic_section)      def _parse(self) -> None:         self._parsed_lines = self._consume_empty()


Question: Napoleon: more custom docstring section styles Although the option help renders custom docstring section, the style is inconsistent with the rest of the doc. For example, I have a custom docstring section . I would like it to be displayed as or docstring section. However, option rendesr in a different style shown in the following picture. ! It will be really helpful if we can customize the custom sections a bit more. The following setting has a similar effect, but it renders the Parameters name instead of the custom name. I would like to do something like the following so that my Custom section has the same style as the Parameter section, and it still keeps my custom name: or The following link includes more details about the solutions: Others people have expressed a similar desire (see sphinx-contrib/napoleon) If you are interested, I would like to provide a PR for this. Thanks!

# for now, no admonition for simple custom sections         return self._parse_generic_section(section, False) <ins>    def _parse_custom_params_style_section(self, section: str) -> List[str]:        return self._format_fields(section, self._consume_fields())    def _parse_custom_returns_style_section(self, section: str) -> List[str]:        fields = self._consume_returns_section()        return self._format_fields(section, fields)</ins>     def _parse_usage_section(self, section: str) -> List[str]:         header = ['.. rubric:: Usage:', '']         block = ['.. code-block:: python', '']


Question: Enable passing options to pygments Hi, Related to issue 175 (and discussed on #python-docs), it would be nice to have a way of passing options to pygments. This is essential for small snippets of PHP (the :startsinline: option) - there are probably other cases too. Default options might go in , with sourcecode block options allowed. Thanks Bitbucket: Originally reported by: Paul Biggar Originally created at: 2009-06-23T19:02:39.208

"But `%r' is given." % source_suffix))  <ins>def convert_highlight_options(app: "Sphinx", config: Config) -> None:    """Convert old styled highlight_options to new styled one.    * old style: options    * new style: dict that maps language names to options    """    options = config.highlight_options    if options and not all(isinstance(v, dict) for v in options.values()):        # old styled option detected because all values are not dictionary.        config.highlight_options = {config.highlight_language: options}  # type: ignore</ins> def init_numfig_format(app: "Sphinx", config: Config) -> None:     """Initialize :confval:`numfig_format`."""     numfig_format = {'section': _('Section %s'),


Question: Enable passing options to pygments Hi, Related to issue 175 (and discussed on #python-docs), it would be nice to have a way of passing options to pygments. This is essential for small snippets of PHP (the :startsinline: option) - there are probably other cases too. Default options might go in , with sourcecode block options allowed. Thanks Bitbucket: Originally reported by: Paul Biggar Originally created at: 2009-06-23T19:02:39.208

def setup(app: "Sphinx") -> Dict[str, Any]:     app.connect('config-inited', convert_source_suffix, priority=800)    app.connect('config-inited', convert_highlight_options, priority=800)     app.connect('config-inited', init_numfig_format, priority=800)     app.connect('config-inited', correct_copyright_year, priority=800)     app.connect('config-inited', check_confval_types, priority=800)diff --git a/sphinx/writers/html.py b/sphinx/writers/html.py-- a/sphinx/writers/html.py++ b/sphinx/writers/html.py


Question: Enable passing options to pygments Hi, Related to issue 175 (and discussed on #python-docs), it would be nice to have a way of passing options to pygments. This is essential for small snippets of PHP (the :startsinline: option) - there are probably other cases too. Default options might go in , with sourcecode block options allowed. Thanks Bitbucket: Originally reported by: Paul Biggar Originally created at: 2009-06-23T19:02:39.208

linenos = node.get('linenos', False)         highlight_args = node.get('highlight_args', {})         highlight_args['force'] = node.get('force', False)        if lang == self.config.highlight_language:            # only pass highlighter options for original language            opts = self.config.highlight_options        else:            opts = {}        opts = self.config.highlight_options.get(lang, {})          if linenos and self.config.html_codeblock_linenos_style:             linenos = self.config.html_codeblock_linenos_stylediff --git a/sphinx/writers/html5.py b/sphinx/writers/html5.py-- a/sphinx/writers/html5.py++ b/sphinx/writers/html5.py