Игнорировать предупреждения Sphinx autodoc для значений rtype

Прямо сейчас autodoc, кажется, выдает предупреждения для любого значения rtype, которое не является просто типом объекта (экземпляр класса, int, список, словарь и т. д.). Таким образом, возвращаемое значение, такое как список кортежей, вызовет предупреждение. Есть ли способ игнорировать эти предупреждения (по отдельности или в целом)? Я не хочу игнорировать весь файл, только эти конкретные предупреждения.

Примером этого предупреждения может быть что-то вроде:

/path/to/code.py:docstring of path.to.code.method:: WARNING: py:class reference target not found: list of tuples

И в некоторых случаях я вижу ошибки для объектов, которые, как я знаю, являются законными классами, импортированными в код, например:

/path/to/code.py:docstring of path.to.code.method:: WARNING: py:class reference target not found: Response

В этом примере Response является частью rest_framework.response, поэтому это довольно часто используемый объект класса.

Эти предупреждения появляются каждый раз, когда я создаю новую документацию. Не ясно, что это может быть воспроизведено в другой среде.


python-sphinx autodoc
person Joe Auerbach    schedule 29.01.2021    source источник
comment
Что такое предупреждающее сообщение? Как мы можем воспроизвести проблему?   -  person mzjn    schedule 29.01.2021
comment
Обновлено. благодаря.   -  person Joe Auerbach    schedule 29.01.2021
comment
Вам необходимо установить все пакеты, на которые есть ссылки в вашей виртуальной среде, где также установлен Sphinx.   -  person Steve Piercy    schedule 30.01.2021
comment
У вас есть nitpicky = True в conf.py? См. sphinx-doc.org/en/master/usage. /   -  person mzjn    schedule 30.01.2021
comment
Опять же: как мы можем воспроизвести это? См. минимально воспроизводимый пример.   -  person mzjn    schedule 01.02.2021
comment
Если у вас есть решение, опубликуйте его как ответ. Не публикуйте решения, редактируя Вопрос.   -  person mzjn    schedule 02.02.2021

Ответы (1)


arrow_upward
0
arrow_downward

Решение здесь заключалось в том, что рассматриваемые классы не находились в toctree, поэтому не были частью документов. По сути, autodocs хочет иметь возможность ссылаться на классы, упомянутые в переменных типа. Если он не может этого сделать, он выдаст ошибку, в которой говорится, что я понятия не имею, что такое Response (или какой-либо другой класс, который вы возвращаете). Не ошибка, потому что он предположил, что вы правы, а предупреждение о том, что он не может его найти. Таким образом, решение здесь состояло в том, чтобы создать index.rst, который включал класс, затем Response.rst (например), включая относительный путь к классу. Ниже приведен пример этого процесса. Предполагается, что Response находится в rest.py.

error:  /path/to/code.py:docstring of the.code.rest.GetAccount.get:: WARNING: py:class reference target not found: Response

В моем случае для этого потребовалось следующее:

  1. добавить строку для response в modules/code/rest.rst
  2. добавить response.rst в тот же каталог
  3. включите строку `.. automodule::code.rest.Response

Затем удалите и перестройте документы, и все должно быть хорошо.

person Joe Auerbach    schedule 02.02.2021