YLk^dZddlZddlZddlZddlZddlmZddlm Z m Z m Z ddl m Z mZdZej eZdZdZd Zd Zd Zd Zigfd ZigfdZdZdZdZdZy)a Customizations for and integration with the Sphinx_ documentation generator. The :mod:`humanfriendly.sphinx` module uses the `Sphinx extension API`_ to customize the process of generating Sphinx based Python documentation. To explore the functionality this module offers its best to start reading from the :func:`setup()` function. .. _Sphinx: http://www.sphinx-doc.org/ .. _Sphinx extension API: http://sphinx-doc.org/extdev/appapi.html N) get_aliases)compactdedentformat) USAGE_MARKER render_usage) deprecation_note_callbackenable_deprecation_notesenable_man_roleenable_pypi_roleenable_special_methodsenable_usage_formattingloggerman_role pypi_rolesetupspecial_methods_callbackusage_message_callbackct|tjr|rt|j}|rt dj |g}|jdd}t|dk(rd} nd} |j|t| z|jD]@\}} |jtd|||jtd|d z| Bt|d j |y y y y ) aZ Automatically document aliases defined using :func:`~humanfriendly.deprecation.define_aliases()`. Refer to :func:`enable_deprecation_notes()` to enable the use of this function (you probably don't want to call :func:`deprecation_note_callback()` directly). This function implements a callback for ``autodoc-process-docstring`` that reformats module docstrings to append an overview of aliases defined by the module. The parameters expected by this function are those defined for Sphinx event callback functions (i.e. I'm not going to document them here :-).  z.. note:: Deprecated namesz a+ The following alias exists to preserve backwards compatibility, however a :exc:`~exceptions.DeprecationWarning` is triggered when it is accessed, because this alias will be removed in a future release. a2 The following aliases exist to preserve backwards compatibility, however a :exc:`~exceptions.DeprecationWarning` is triggered when they are accessed, because these aliases will be removed in a future release. z%s.. data:: %sz%sAlias for :obj:`%s`.z N) isinstancetypes ModuleTyper__name__rjoinappendlenritemsr update_lines) appwhatnameobjoptionslinesaliasesblocksindent explanationtargets 9/usr/lib/python3.12/site-packages/humanfriendly/sphinx.pyr r 4s#u''(Ucll+  TYYu-./F MM6 7F7|q   MM&7;#77 8 '  f f%5vtDE f%=vz6RS!0  F 3 4; .3(c0|jdty)aK Enable documenting backwards compatibility aliases using the autodoc_ extension. :param app: The Sphinx application object. This function connects the :func:`deprecation_note_callback()` function to ``autodoc-process-docstring`` events. .. _autodoc: http://www.sphinx-doc.org/en/stable/ext/autodoc.html autodoc-process-docstringN)connectr r"s r-r r esKK+-FGr.c0|jdty)z Enable the ``:man:`` role for linking to Debian Linux manual pages. :param app: The Sphinx application object. This function registers the :func:`man_role()` function to handle the ``:man:`` role. manN)add_rolerr2s r-r r ssLL!r.c0|jdty)z Enable the ``:pypi:`` role for linking to the Python Package Index. :param app: The Sphinx application object. This function registers the :func:`pypi_role()` function to handle the ``:pypi:`` role. pypiN)r5rr2s r-r r sLL#r.c0|jdty)a6 Enable documenting "special methods" using the autodoc_ extension. :param app: The Sphinx application object. This function connects the :func:`special_methods_callback()` function to ``autodoc-skip-member`` events. .. _autodoc: http://www.sphinx-doc.org/en/stable/ext/autodoc.html zautodoc-skip-memberN)r1rr2s r-r r sKK%'?@r.c0|jdty)aQ Reformat human friendly usage messages to reStructuredText_. :param app: The Sphinx application object (as given to ``setup()``). This function connects the :func:`usage_message_callback()` function to ``autodoc-process-docstring`` events. .. _reStructuredText: https://en.wikipedia.org/wiki/ReStructuredText r0N)r1rr2s r-rrsKK+-CDr.cd|z}tjj|tjj |fd|i|}|ggfS)a Convert a Linux manual topic to a hyperlink. Using the ``:man:`` role is very simple, here's an example: .. code-block:: rst See the :man:`python` documentation. This results in the following: See the :man:`python` documentation. As the example shows you can use the role inline, embedded in sentences of text. In the generated documentation the ``:man:`` text is omitted and a hyperlink pointing to the Debian Linux manual pages is emitted. zhttps://manpages.debian.org/%srefuridocutilsnodes referenceutilsunescape) rolerawtexttextlinenoinlinerr&contentman_urlr?s r-rrsK$/5G(((..2I2I$2OkX_kcjkI ;?r.cd|z}tjj|tjj |fd|i|}|ggfS)a Generate hyperlinks to the Python Package Index. Using the ``:pypi:`` role is very simple, here's an example: .. code-block:: rst See the :pypi:`humanfriendly` package. This results in the following: See the :pypi:`humanfriendly` package. As the example shows you can use the role inline, embedded in sentences of text. In the generated documentation the ``:pypi:`` text is omitted and a hyperlink pointing to the Python Package Index is emitted. zhttps://pypi.org/project/%s/r;r<) rBrCrDrErFr&rGpypi_urlr?s r-rrsK$.4H(((..2I2I$2OlX`ldklI ;?r.cddlm}t|t|t |t |t |tdd|S)a Enable all of the provided Sphinx_ customizations. :param app: The Sphinx application object. The :func:`setup()` function makes it easy to enable all of the Sphinx customizations provided by the :mod:`humanfriendly.sphinx` module with the least amount of code. All you need to do is to add the module name to the ``extensions`` variable in your ``conf.py`` file: .. code-block:: python # Sphinx extension module names. extensions = [ 'sphinx.ext.autodoc', 'sphinx.ext.doctest', 'sphinx.ext.intersphinx', 'humanfriendly.sphinx', ] When Sphinx sees the :mod:`humanfriendly.sphinx` name it will import the module and call its :func:`setup()` function. This function will then call the following: - :func:`enable_deprecation_notes()` - :func:`enable_man_role()` - :func:`enable_pypi_role()` - :func:`enable_special_methods()` - :func:`enable_usage_formatting()` Of course more functionality may be added at a later stage. If you don't like that idea you may be better of calling the individual functions from your own ``setup()`` function. r) __version__T)parallel_read_safeparallel_write_safeversion) humanfriendlyrLr r r r rdict)r"rLs r-rrs?F*S!CS3C 4T; WWr.cvt|ddr+t|tjtjfry|S)a Enable documenting "special methods" using the autodoc_ extension. Refer to :func:`enable_special_methods()` to enable the use of this function (you probably don't want to call :func:`special_methods_callback()` directly). This function implements a callback for ``autodoc-skip-member`` events to include documented "special methods" (method names with two leading and two trailing underscores) in your documentation. The result is similar to the use of the ``special-members`` flag with one big difference: Special methods are included but other types of members are ignored. This means that attributes like ``__weakref__`` will always be ignored (this was my main annoyance with the ``special-members`` flag). The parameters expected by this function are those defined for Sphinx event callback functions (i.e. I'm not going to document them here :-). __doc__NF)getattrrr FunctionType MethodType)r"r#r$r%skipr&s r-rrs2&sIt$C%:L:LeN^N^9_)` r.cl|r|j|r|j|jy)z;Private helper for ``autodoc-process-docstring`` callbacks.N)popextend splitlines)r'rDs r-r!r!s&    LL"#r.ct|tjrC|r@|djtr't dj |}t||yyyy)a Reformat human friendly usage messages to reStructuredText_. Refer to :func:`enable_usage_formatting()` to enable the use of this function (you probably don't want to call :func:`usage_message_callback()` directly). This function implements a callback for ``autodoc-process-docstring`` that reformats module docstrings using :func:`.render_usage()` so that Sphinx doesn't mangle usage messages that were written to be human readable instead of machine readable. Only module docstrings whose first line starts with :data:`.USAGE_MARKER` are reformatted. The parameters expected by this function are those defined for Sphinx event callback functions (i.e. I'm not going to document them here :-). rrN)rrr startswithrrrr!)r"r#r$r%r&r'rDs r-rr#sR$#u''(U 8  | , % 01D  % -.3(r.)rSloggingrdocutils.nodesr=docutils.utilshumanfriendly.deprecationrhumanfriendly.textrrrhumanfriendly.usagerr__all__ getLoggerrrr r r r r rrrrrr!rr.r-rgs  266:    8 $.5b H " $ A E<>r.=?.+X\2$&r.