Usando esfinge com Markdown em vez de RST

212

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

digi604
fonte
1
Não conheço nenhuma opção disponível para isso. Mas observe que o RST tem muito mais opções do que descontos em termos de extensibilidade. Portanto, dependendo do seu projeto, pode não ser suficiente.
Wolph 21/03/10
2
Há um subconjunto de rST que é basicamente uma redução válida. Se você odeia listas de campos da Esfinge ( :param path:etc), consulte Extensão de Napoleão .
Beni Cherniavsky-Paskin
3
Se você gostaria de documentar seu projeto Python no Markdown com Esfinge, voto para o pedido de recurso no bitbucket.org/birkenfeld/sphinx/issue/825/...
Coronel Pânico
1
Olhando para este comentário, parece que você pode misturar os dois: read-the-docs.readthedocs.org/en/latest/...
Stefan van der Walt
2
Suporte Markdown Básico finalmente fez seu caminho em Esfinge: veja nova resposta
Oliver Bestwalter

Respostas:

97

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 .

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 .

Beni Cherniavsky-Paskin
fonte
17
Concluo que, devido à falta de progresso nessa área, o ReST pode ser bom o suficiente e não suficientemente diferente, de modo que o Markdown pode valer a pena para esse empreendimento.
Prof. Falken
5
TLDR: use recommonmark para escrever a documentação do Sphinx usando o Markdown.
Ostrokach #
sugira adicionar o novo myst-parsera esta resposta. vai ganhar.
Rick apoia Monica
92

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.

Marijn
fonte
4
Beni menciona essa abordagem em sua resposta muito abrangente acima . No entanto, sinto que esta pergunta merece esta resposta simples.
Marijn
2
É importante ler recommonmark.readthedocs.org/en/latest/auto_structify.html , especialmente como criar uma toctree e como usar um eval_rstbloco cercado para inserir qualquer diretiva / construção rST.
Beni Cherniavsky-Paskin / 02/15
este necessário para instalar recommonmark e commonmark
XavierCLL
1
Eu entro ImportError: cannot import name 'DocParser'no Sphinx 1.4.1 no Python 3.4.3.
detly
2
@detly: O ImportError é devido à versão mais recente do commonmark (0.6.0) que quebra a compatibilidade com o recommonmark: consulte github.com/rtfd/recommonmark/issues/24 . A solução:pip install commonmark==0.5.5 --upgrade
kadee 8/08/16
30

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.

jkmacc
fonte
5
Os MkDocs também funcionaram muito bem aqui, para documentação do usuário final. Ainda olhando para uso remarcação dentro docstrings ..
Marcus Ottosson
2
Tanta sim para isso.
Jkmacc
1
Ei, obrigado - MkDocs é incrível! Perco muito poder e recursos em comparação com o Sphinx e o RST, isso é certo ... mas é incrivelmente descomplicado, simplificado e tão fácil e rápido de usar. Perfeito para quase todos os meus casos de uso - como instruções curtas de instalação e algum tutorial de início rápido com alguns exemplos. Nos poucos casos em que preciso de muita explicação do código-fonte - documentação da classe ig e das chamadas de funções -, continuo no Sphinx.
Brutus
No momento em que escrevemos isso, ele suporta apenas 2 níveis de recuo do TOC.
Wrygiel
@wrygiel Você não está certo - o número de níveis de sumário processados ​​depende do tema que você está usando.
Ale
27

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']
Oliver Bestwalter
fonte
1
Se você conseguir cannot import name DocParser, tente pip install commonmark==0.5.5.
Roger Dahl
1
Link em docs esfinge deve ser sphinx-doc.org/en/master/usage/markdown.html
Paul Brannan
21

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.

bewest
fonte
5
"Parece razoável querer referenciar seus bits de conteúdo do Markdown do seu projeto de esfinge" - é realmente isso que eu quero fazer; Eu quero incluir algum conteúdo de remarcação (meu README.md) na minha documentação mais abrangente do Sphinx. Você sabe se isto é possível?
detly
8

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(' '))
igniteflow
fonte
1

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.

the_drow
fonte
3
A menos que eu esteja fazendo algo errado, não é tão fácil substituir o ReST pelo Markdown. Se você usar instruções como toctree no arquivo de origem do Markdown, o Pandoc as mudará para uma única linha: .. toctree:: :maxdepth: 2 :glob:durante a transformação e elas pararão de funcionar. Em outras palavras, é impossível usar diretivas dessa maneira.
Wiktor Walc
@WiktorWalc Eu não estou muito familiarizado com o pandoc e realmente não tentei, mas fazia sentido, eu acho. Ah bem. Eu tentei. Eu acho que você pode registrar um relatório de bug?
21313 as
@WiktorWalc: ..toctreenão é uma sintaxe válida do Markdown. Você escreve o documento inteiro no Markdown (e perde a gentileza do ReSt) ou usa o ReST. Você não pode ter seu bolo e comê-lo também.
Aditya
1
apenas uma dica: uma solução seria usar filtros pandoc para ignorar essas instruções especiais e deixá-las como estão na geração de saída. Porém, eu não sou um mago de filtros pandoc, e isso adiciona complexidade extra ao esquema.
Zmo
0

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>
Donatello
fonte