Строки документации Sphinx и vscode
У меня есть следующая строка документации:
def test(foo):
"""this is my function
.. code-block:: python
cool function
now I should be outside the codeblock.
But I'm not?
.. code-block:: python
next function
I'm still inside the original codeblock?
:param foo: _description_
:type foo: _type_
"""
Что отображается в VScode следующим образом:
Я неправильно пишу синтаксис или VScode просто не справляется с рендерингом формата сфинкса?
1) Я использую стиль reStructuredText (Sphinx), чтобы в дальнейшем создавать документацию в Sphinx. 2) Я попробовал добавить пустую строку, не помогло.
Понятно. Существует два основных стиля документации; reST — это общий подъязык, который приложение Sphinx использует для создания документов. Стиль Google и стиль numpy. Выбирайте одно, не смешивайте. По ссылкам есть хорошие примеры строк документации. Кроме того, вам, возможно, придется указать VSC, какой стиль ожидать. (Я использую Spyder, и есть опция для стиля документации.)
И, как вы, возможно, знаете, существует PEP-257, который описывает стили документации на уровне Python.
Насколько я понимаю, я не смешиваю стили, а придерживаюсь того стиля, который предписывает сфинкс? sphinx-rtd-tutorial.readthedocs.io/en/latest/docsrings.html Кроме того, я, кажется, сообщил VSC, что использую стиль Sphinx: i.imgur.com/ak1cxCR.png
Каков желаемый эффект? Как вы думаете, где это искажение?
Теперь мне удалось составить правильную документацию по сфинксу, и вывод сфинкса в формате HTML выглядит хорошо. Однако VScode по-прежнему отображает его неправильно. Пожалуйста, посмотрите это изображение для дальнейшего объяснения: imgur.com/a/4uiMYTk Я считаю, что после удаления отступов из кодовых блоков следует выйти.
AFAIK Visual Studio Code не может сделать это без дополнительного плагина, или, по крайней мере, я никогда не видел, чтобы он мог это сделать. PyCharm, альтернативная IDE, здесь справляется несколько лучше.
Ответы 1
Есть два способа добиться правильного отображения.
1. Добавьте уровень отступов для блоков кода.
def test(foo):
"""this is my function
.. code-block:: python
cool function
now I should be outside the codeblock.
But I'm not?
.. code-block:: python
next function
I'm still inside the original codeblock?
:param foo: _description_
:type foo: _type_
"""
2. Удалить один уровень отступов для некодовых блоков.
def test(foo):
"""this is my function
.. code-block:: python
cool function
now I should be outside the codeblock.
But I'm not?
.. code-block:: python
next function
I'm still inside the original codeblock?
:param foo: _description_
:type foo: _type_
"""
Я не уверен, правильный ли это синтаксис или это ошибка vscode. Если кто-то считает, что это ошибка, вы можете сообщить об этом на GitHub и поделиться ссылкой здесь.
Это неверный синтаксис реструктурированного текста. Я думаю, что код Visual Studio здесь предполагает Markdown.
Я не уверен, есть ли здесь в языке синтаксическая ошибка, но ваше 2. предложение работает просто великолепно! Я получаю красивый рендеринг vscode, а sphinx также создает HTML с правильными блоками кода и отступами. Большое спасибо
1) Какой стиль строк документации вы собираетесь использовать? 2) Я думаю, после директивы блока кода должна быть пустая строка.