Sphinx autodoc и многострочные строки

У меня есть модуль python, который определяет многострочную строковую константу. Я хочу, чтобы многострочная строка хорошо отображалась в документации на основе Sphinx.

Ниже приведен пример кода Python, RST и того, как он отображается с помощью sphinx-build. Однако я бы предпочел получить что-то вроде «желаемых документов сфинкса».

Это возможно?

mymodule.py

#: Default configuration
DEFAULT_CONFIG = r"""
{ "foo": "bar",
  "baz": "rex" }
"""

mydocs.rst

...

--------------
Default Config
--------------

.. autodata:: mymodule.DEFAULT_CONFIG

Результирующие документы Sphinx

mymodule.DEFAULT_CONFIG
= "{ \"foo\": \"bar\",\n  \"bar\": \"rex\" }"

str(object=’‘) -> str str(bytes_or_buffer[, encoding[, errors]]) -> str

Create a new string object from the given object.
If encoding or errors is specified, then the object
must expose a data buffer that will be decoded using
the given encoding and error handler. Otherwise, returns
the result of object.__str__() (if defined) or repr(object).
encoding defaults to sys.getdefaultencoding(). errors defaults to ‘strict’.

Желаемые документы Sphinx

mymodule.DEFAULT_CONFIG = Default configuration
{ "foo": "bar",
  "baz": "rex" }

python python-sphinx autodoc
person Manuel    schedule 22.01.2017    source источник

Ответы (1)


arrow_upward
4
arrow_downward

Это не может поддерживаться напрямую, но, поскольку вы используете Sphinx и Python, я решил пойти со следующим хаком:

  1. В этом примере важно, чтобы вы могли import указать желаемую переменную. Это уже должно работать, так как autodoc может производить вывод.

  2. Этот хак позволит вам получить более удобный для человека вывод, но вы все равно будете также иметь значение переменной (насколько это касается sphinx) в нежелательном ( с кучей \n символов).

Я буду повторно использовать для этого свой собственный проект, но с вашей переменной/значением. Имя моего пакета — exhale, а файл, в который я его помещаю, — exhale/configs.py, так что вот откуда все это. Итак, вот макет:

Файл: exhale/configs.py

Это ваш фактический код Python. Это выглядит так:

__name__ = "configs"
__docformat__ = "reStructuredText"

DEFAULT_CONFIG = r"""
{ "foo": "bar",
  "baz": "rex" }
"""
'''
This is some description of the use of / intended purpose of the variable.

The contents of this variable are a multi-line string with value:

.. include:: DEFAULT_CONFIG_value.rst

.. note::

   The above value is presented for readability, take special care in use of
   this variable that the real value has both a leading and trailing ``\\n``.
'''

В вашей документации по сфинксу

В каком бы файле у вас не было autodata выше (я использовал automodule, это не имеет значения). Документы выглядят следующим образом (для ясности, вы уже получили это, и не нужно его менять). Что вам нужно изменить, так это вашу фактическую строку документации python и следующий раздел. Это здесь для полноты ответа.

Exhale Configs Module
=====================

.. automodule:: exhale.configs
   :members:
   :undoc-members:

Измените свой conf.py

Это интересная часть и огромное преимущество использования Sphinx — Python чертовски удобен, когда дело доходит до записи файлов. В приведенной выше строке документации вы увидите, что я преднамеренно использую директиву .. include. Сумасшедшая часть этого заключается в том, что мы можем динамически записывать этот файл. Внизу вашего conf.py вы можете просто добавить что-то вроде

# Import the variable from wherever it lives
from exhale.configs import DEFAULT_CONFIG
default_parts = DEFAULT_CONFIG.strip().splitlines()
# Because I am deliberately putting this underneath a '.. code-block:: py',
# we need to indent by **THREE** spaces.
#
# Similarly, when writing to the file, the "\n\n   " before
# {default_config_value} (the three spaces) is also important ;)
default_config_value = "\n   ".join(p for p in default_parts)
with open("DEFAULT_CONFIG_value.rst", "w") as dcv:
    dcv.write(".. code-block:: py\n\n   {default_config_value}\n\n".format(
        default_config_value=default_config_value
    ))

Если вы используете Python 3, вместо разделения и объединения просто используйте textwrap.indent. Я сделал это только для того, чтобы убедиться, что пользователи Python 2 могут копировать.

КАБУМ

При запуске make html файл DEFAULT_CONFIG_value.rst будет создаваться каждый раз заново! Поэтому, даже если вы измените значение переменной, все должно быть хорошо. Для справки, сгенерированный файл у меня выглядит так

.. code-block:: py

   { "foo": "bar",
     "baz": "rex" }

Примечание: это не отдельный документ reStructuredText, его следует использовать только через .. include::!

И последнее, но не менее важное: визуализированный вывод выглядит следующим образом:

сгенерированные сфинксом документы

Как указано в преамбуле, Sphinx включит версию \n в значение. Мы просто помещаем это в строку документации. Очень полезно иметь оба. Причина в том, что с подходом .. code-block:: py Sphinx будет удалять начальные/конечные символы новой строки (отсюда и .. note:: в строке документации). Поэтому очень полезно иметь удобочитаемую версию, но также полезно знать необработанное значение.

Единственное, что здесь стоит упомянуть, это то, что нет предела возможностям! Я решил использовать .. code-block:: py для своих целей, но, поскольку вы буквально сами пишете файл, вы можете делать все, что хотите. Вы можете написать файл так, чтобы вместо этого он производил

.. code-block:: py

   DEFAULT_CONFIG = r"""
   { "foo": "bar",
     "baz": "rex" }
   """

изменив часть в conf.py. Тебе решать! При изменении вывода вы можете получить ошибки, откройте сгенерированный документ .rst и убедитесь, что он действителен :)

person svenevs    schedule 22.08.2017