How do I reference a documented Python function parameter using Sphinx markup?

前端 未结 4 1209
闹比i
闹比i 2021-02-06 21:29

I\'d like to reference a previously-documented function parameter elsewhere in a Python docstring. Consider the following (admittedly completely artificial) example:

         


        
4条回答
  •  野趣味
    野趣味 (楼主)
    2021-02-06 21:45

    If you are looking for a way to link directly to the bar definition of foo then your documentation is too lengthy or you are asking your reader to ignore the forest for one tree or some combination of the two.

    Taking an example from defaultdict Examples:

    Setting the :attr:`default_factory` to :class:`int` makes the
    :class:`defaultdict` useful for counting (like a bag or multiset in other
    languages):
    

    if I can't be bothered to read five sentences into collections.defaultdict to find the meaning of default_factory I probably don't deserve to be lead there.

    Note that the attribute reference syntax is the same as in the section above:

    The first argument provides the initial value for the :attr:`default_factory`
    attribute; it defaults to ``None``.
    

    but it looks like Sphinx doesn't reach out of the current section scope and so renders the later reference as styled text rather than as an anchor. It would not surprise me if this was intentional.

提交回复
热议问题