Заставить Сфинкса интерпретировать Markdown в строках документации Python вместо reStructuredText - PullRequest
Новая
       22

Заставить Сфинкса интерпретировать Markdown в строках документации Python вместо reStructuredText

1 голос
/ 09 мая 2019

Я использую Sphinx для документирования проекта на Python.Я хотел бы использовать Markdown в моих строках документов для их форматирования. Даже если я использую расширение recommonmark, оно охватывает только файлы .md, написанные вручную, а не строки документации.

Я использую autodoc, napoleon и recommonmarkв моих расширениях.

Как мне сделать разметку разбора сфинкса в моих строках документов?

1 Ответ

2 голосов
/ 03 июня 2019
Расширение

Sphinx autodoc генерирует событие с именем autodoc-process-docstring каждый раз, когда обрабатывает строку документа.Вы можете подключиться к этому механизму для преобразования синтаксиса из Markdown в reStructuredText.

Я не знаю, почему recommonmark не предлагает такую ​​функциональность из коробки.Это должно быть легко добавить.Лично я использую m2r для конвертации в моих проектах.Потому что это быстро - намного быстрее, чем, например, pandoc.Скорость важна, так как преобразование происходит на лету и обрабатывает каждую строку документа в отдельности.Кроме этого, подойдет любой конвертер Markdown-to-reST.

Установите m2r и добавьте следующее в файл конфигурации Sphinx conf.py: 

import m2r

def docstring(app, what, name, obj, options, lines):
    md  = '\n'.join(lines)
    rst = m2r.convert(md)
    lines.clear()
    for line in rst.splitlines():
        lines.append(line)

def setup(app):
    app.connect('autodoc-process-docstring', docstring)

[ Отредактированодобавить… ]

Как и выше, но с commonmark: 

import commonmark

def docstring(app, what, name, obj, options, lines):
    md  = '\n'.join(lines)
    ast = commonmark.Parser().parse(md)
    rst = commonmark.ReStructuredTextRenderer().render(ast)
    lines.clear()
    for line in rst.splitlines():
        lines.append(line)

def setup(app):
    app.connect('autodoc-process-docstring', docstring)

При этом используется тот же анализатор Markdown, что и в расширении Sphinx recommonmark и так же быстро, как m2r, что означает почти полное отсутствие влияния на время сборки по сравнению с собственным reStructuredText.

...