Как добавить авторство в строку документации NumPy в Python

Мы перешли с Sphinx на стиль строки документации NumPy, и .. sectionauthor:: больше не кажется, визуализировать правильно. Тем не менее, нам нужно иметь возможность назначать автора каждому методу класса.

Есть ли способ правильно добавить авторство в строку документации NumPy?

Наивный пример:

class A:
    def f(self):
        """ My function

        It does this and that.

        Returns
        -------
        object

        .. sectionauthor:: name of the author

        Examples
        --------
            >>> A().f()

        """
        pass

Компилируется в этот справочный документ (обратите внимание на проблемный раздел returns:):

введите здесь описание изображения

P.S. Использование .. sectionauthor:: в строке документации NumPy было предложено в другом месте (не могу вспомнить источник), поэтому, возможно, оно просто неправильно используется/размещено.


person Oleg Melnikov    schedule 27.11.2015    source источник
comment
Что вы используете для рендеринга docstring. Я не знаю, есть ли у numpy собственный стиль или механизм рендеринга (отличный от Python docstring).   -  person hpaulj    schedule 27.11.2015
comment
Рендеринг встроен в PyCharm, но я не знаю, какой пакет использует PyCharm. Это делается с помощью инструмента Quick Documentation (или CTRL+Q) и выводит HTML (я думаю), который показан на экране печати выше.   -  person Oleg Melnikov    schedule 28.11.2015
comment
Хорошо, это метаданные в reStructuredText, которые, вероятно, обрабатываются docutils.   -  person hpaulj    schedule 28.11.2015


Ответы (1)


догадаться...

Прежде всего, документация в стиле NumPy не рекомендует добавлять информацию об авторах в строку документации: «Обратите внимание, что лицензия и информация об авторе, хотя они часто включаются в исходные файлы, не относятся к строкам документации.»

Тем не менее, нередко авторы указываются непосредственно в документации (см. любое справочное руководство по функциям/методам в языке R).

Тем не менее, если возникнет необходимость добавить авторов, это можно сделать с помощью :Authors: reStructured встроенная разметка следующим образом:

:Authors:
    John Doe <[email protected]>

Как выяснилось, его размещение ограничено. :Authors:, кажется, по-прежнему правильно отображает строку документации, если размещать ее подальше от описаний, параметров и разделов возврата; например, после раздела Examples.

Вот продолжение примера:

введите описание изображения здесь

person Oleg Melnikov    schedule 27.11.2015
comment
Это уголок numpy, на который я не обращал особого внимания, хотя я все время читаю документы по функциям. - person hpaulj; 28.11.2015