Usando esfinge com Markdown em vez de RST

Eu odeio RST, mas amo esfinge. Existe uma maneira pela qual a Esfinge lê a remarcação em vez de reStructuredText?

A maneira "adequada" de fazer isso seria escrever um analisador de documentos para remarcação. (Além disso, uma opção Sphinx para escolher o analisador.) A vantagem disso seria o suporte instantâneo a todos os formatos de saída de documentos (mas você pode não se importar com isso, pois já existem ferramentas semelhantes de remarcação para a maioria). Maneiras de abordar isso sem desenvolver um analisador do zero:

1. Você pode trapacear e escrever um "analisador" que usa o Pandoc para converter a remarcação em RST e passar isso para o analisador de RST :-).

2. Você pode usar um analisador existente de markdown-> XML e transformar o resultado (usando XSLT?) No esquema docutils.

3. Você pode pegar um analisador python markdown existente que permite definir um renderizador personalizado e fazer com que ele construa a árvore de nós do docutils.

4. Você pode bifurcar o leitor RST existente, copiando tudo o que é irrelevante para descontos e alterando as diferentes sintaxes ( essa comparação pode ajudar) ...
   EDIT: Não recomendo esta rota, a menos que você esteja preparado para testá-la intensamente. O Markdown já tem muitos dialetos sutilmente diferentes e isso provavelmente resultará em mais um ...

ATUALIZAÇÃO: https://github.com/sgenoud/remarkdown é um leitor de descontos para docutils. Ele não pegou nenhum dos atalhos acima, mas usa uma gramática Parsley PEG inspirada no peg-markdown .

• Ainda não suporta diretivas.

UPDATE: https://github.com/readthedocs/recommonmark e é outro leitor de documentos, com suporte nativo no ReadTheDocs. Derivado da observação, mas usa o analisador CommonMark-py .

• Ele pode converter sintaxes Markdown específicas mais ou menos naturais em estruturas apropriadas, por exemplo, lista de links para uma árvore de toc. * Não possui sintaxe nativa genérica para funções.
• Oferece suporte à incorporação de qualquer conteúdo rST, incluindo diretivas, com um ```eval_rstbloco vedado , bem como uma abreviação de diretivas DIRECTIVE_NAME:: ....

ATUALIZAÇÃO : O MyST é mais um leitor de docutins / Sphinx. Baseado em markdown-it-py, compatível com CommonMark.

• Possui uma {ROLE_NAME}`...`sintaxe genérica para funções.
• Possui uma sintaxe genérica para diretivas com ```{DIRECTIVE_NAME} ...blocos protegidos.

Em todos os casos, você precisará inventar extensões do Markdown para representar diretivas e funções do Sphinx . Embora você não precise de todos eles, alguns .. toctree::são essenciais.
Eu acho que essa é a parte mais difícil. O reStructuredText antes das extensões do Sphinx já era mais rico que a redução. Mesmo a redução acentuada, como a de pandoc , é principalmente um subconjunto do conjunto de recursos rST. Isso é muito terreno para cobrir!

Em termos de implementação, a coisa mais fácil é adicionar uma construção genérica para expressar qualquer função / diretiva de documento. Os candidatos óbvios à inspiração de sintaxe são:

• Sintaxe de atributo, que o pandoc e algumas outras implementações já permitem em muitas construções inline e de bloco. Por exemplo `foo`{.method}-> `foo`:method:.
• HTML / XML. Da <span class="method">foo</span>abordagem mais simples de inserir apenas docutils XML interno!
• Algum tipo de YAML para diretivas?

Mas esse mapeamento genérico não será a solução mais isenta de descontos ... Atualmente, os lugares mais ativos para discutir extensões de descontos são https://groups.google.com/forum/#!topic/pandoc-discuss , https: // github.com/scholmd/scholmd/

Isso também significa que você não pode simplesmente reutilizar um analisador de remarcação sem estendê-lo de alguma forma. Pandoc novamente faz jus à sua reputação como o canivete suíço de conversão de documentos, apoiando filtes personalizados . (De fato, se eu fosse abordar isso, tentaria criar uma ponte genérica entre leitores / transformadores / gravadores de documentos e leitores / filtros / gravadores de pandoc. É mais do que você precisa, mas o retorno será muito maior do que apenas a esfinge / remarcação.)

Idéia maluca alternativa: em vez de estender o markdown para lidar com o Sphinx, estenda o reStructuredText para suportar (principalmente) um superconjunto de markdown! A beleza é que você poderá usar os recursos do Sphinx como está, e ainda assim poderá escrever a maior parte do conteúdo na remarcação.

Já existe considerável sobreposição de sintaxe ; mais notavelmente a sintaxe do link é incompatível. Eu acho que se você adicionar suporte ao RST para links de remarcação e ###cabeçalhos de estilo e alterar a `backticks`função padrão para literal, e talvez alterar blocos recuados para significar literal (o RST suporta > ...cotações hoje em dia), você obterá algo utilizável que suporta a maioria das remarcações .

Você pode usar o Markdown e o reStructuredText no mesmo projeto do Sphinx. Como fazer isso está documentado de forma sucinta no Read The Docs .

Instale recommonmark ( pip install recommonmark) e edite conf.py:

from recommonmark.parser import CommonMarkParser

source_parsers = {
    '.md': CommonMarkParser,
}

source_suffix = ['.rst', '.md']

Eu criei um pequeno projeto de exemplo no Github (serra / esfinge-com-markdown) demonstrando como (e isso) ele funciona. Ele usa o CommonMark 0.5.4 e recommonmark 0.4.0.

Isso não usa o Sphinx, mas o MkDocs criará sua documentação usando o Markdown. Eu também odeio primeiro, e realmente gostei de MkDocs até agora.

Atualização: isso agora é oficialmente suportado e documentado nos documentos do sphinx .

Parece que uma implementação básica chegou ao Sphinx, mas a palavra ainda não chegou. Veja o comentário da edição do github

instalar dependências:

pip install commonmark recommonmark

ajustar conf.py:

source_parsers = {
    '.md': 'recommonmark.parser.CommonMarkParser',
}
source_suffix = ['.rst', '.md']

Markdown e ReST fazem coisas diferentes.

O RST fornece um modelo de objeto para trabalhar com documentos.

O Markdown fornece uma maneira de gravar pedaços de texto.

Parece razoável querer referenciar seus bits do conteúdo do Markdown do seu projeto sphinx, usando o RST para esboçar a arquitetura geral das informações e o fluxo de um documento maior. Deixe o markdown fazer o que faz, o que permite que os escritores se concentrem em escrever texto.

Existe uma maneira de fazer referência a um domínio de remarcação, apenas para gravar o conteúdo como está? O RST / sphinx parece ter tomado conta de recursos como toctreesem duplicá-los na remarcação.

Agora isso é oficialmente suportado: http://www.sphinx-doc.org/en/stable/markdown.html

Fui com a sugestão de Beni de usar o pandoc para esta tarefa. Uma vez instalado, o script a seguir converterá todos os arquivos de remarcação no diretório de origem em arquivos rst, para que você possa escrever toda a documentação na remarcação. Espero que isso seja útil para os outros.

#!/usr/bin/env python
import os
import subprocess

DOCUMENTATION_SOURCE_DIR = 'documentation/source/'
SOURCE_EXTENSION = '.md'
OUTPUT_EXTENSION = '.rst'

for _, __, filenames in os.walk(DOCUMENTATION_SOURCE_DIR):
    for filename in filenames:
        if filename.endswith('.md'):
            filename_stem = filename.split('.')[0]
            source_file = DOCUMENTATION_SOURCE_DIR + filename_stem + SOURCE_EXTENSION
            output_file = DOCUMENTATION_SOURCE_DIR + filename_stem + OUTPUT_EXTENSION
            command = 'pandoc -s {0} -o {1}'.format(source_file, output_file)
            print(command)
            subprocess.call(command.split(' '))

Existe uma solução alternativa.
O script sphinx-quickstart.py gera um Makefile.
Você pode facilmente chamar Pandoc do Makefile toda vez que desejar gerar a documentação para converter o Markdown em reStructuredText.

Aqui está uma nova opção. O MyST adiciona alguns recursos ao Markdown que permitem ao Sphinx criar documentos como o rst. https://myst-parser.readthedocs.io/en/latest/

Observe que a criação de documentação usando o suporte maven e incorporado ao Sphinx + MarkDown é totalmente suportada pelo seguinte plugin maven:

https://trustin.github.io/sphinx-maven-plugin/index.html

<plugin>
  <groupId>kr.motd.maven</groupId>
  <artifactId>sphinx-maven-plugin</artifactId>
  <version>1.6.1</version>
  <configuration>
    <outputDirectory>${project.build.directory}/docs</outputDirectory>
  </configuration>
  <executions>
    <execution>
      <phase>package</phase>
      <goals>
        <goal>generate</goal>
      </goals>
    </execution>
  </executions>
</plugin>