Utilizzo della sfinge con Markdown anziché RST


212

Odio RST ma amo la sfinge. C'è un modo in cui la sfinge legge markdown invece di reStructuredText?


1
Non sono a conoscenza di alcuna opzione disponibile per questo. Ma nota che RST ha molte più opzioni di markdown in termini di estensibilità. Quindi, a seconda del progetto, potrebbe non essere sufficiente.
Wolph,

2
C'è un sottoinsieme di rST che è per lo più markdown valido. Se odi gli elenchi dei campi Sfinge ( :param path:ecc.), Vedi l' estensione di Napoleone .
Beni Cherniavsky-Paskin,

3
Se desideri documentare il tuo progetto Python in Markdown con Sphinx, vota per la richiesta di funzione su bitbucket.org/birkenfeld/sphinx/issue/825/…
Colonnello Panic,

1
Guardando questo commento, sembra che tu possa mescolare i due: read-the-docs.readthedocs.org/en/latest/…
Stefan van der Walt

2
Il supporto di Markdown di base è finalmente
arrivato

Risposte:


97

Il modo "corretto" per farlo sarebbe quello di scrivere un parser docutils per il markdown . (Più un'opzione Sphinx per scegliere il parser.) La bellezza di questo sarebbe il supporto immediato per tutti i formati di output di docutils (ma potresti non preoccupartene, poiché strumenti di markdown simili esistono già per la maggior parte). Modi per affrontarlo senza sviluppare un parser da zero:

  1. È possibile imbrogliare e scrivere un "parser" che utilizza Pandoc per convertire markdown in RST e passarlo al parser RST :-).

  2. È possibile utilizzare un parser markdown esistente-> XML e trasformare il risultato (usando XSLT?) Nello schema docutils.

  3. Potresti prendere un parser di markdown python esistente che ti consenta di definire un renderer personalizzato e farlo costruire l'albero dei nodi di docutils.

  4. Potresti rovesciare il lettore RST esistente, strappando tutto ciò che è irrilevante per il markdown e cambiando le diverse sintassi ( questo confronto potrebbe aiutare) ...
    EDIT: non consiglio questo percorso a meno che tu non sia disposto a testarlo pesantemente. Markdown ha già troppi dialetti sottilmente diversi e questo probabilmente porterà a un altro ...

AGGIORNAMENTO: https://github.com/sgenoud/remarkdown è un lettore di markdown per docutils. Non ha preso nessuna delle scorciatoie di cui sopra, ma utilizza una grammatica PEG di prezzemolo ispirata al pegging markdown .

AGGIORNAMENTO: https://github.com/readthedocs/recommonmark ed è un altro lettore di docutils, supportato nativamente su ReadTheDocs. Derivato dal commento ma utilizza il parser CommonMark -py .

  • E ' possibile convertire specifiche sintassi più o meno naturali Markdown alla lista di link ad un toctree strutture adeguate ad es. * Non ha una sintassi nativa generica per i ruoli.
  • Supporta l'incorporamento di qualsiasi contenuto rST, comprese le direttive, con un ```eval_rstblocco recintato e una scorciatoia per le direttive DIRECTIVE_NAME:: ....

AGGIORNAMENTO : MyST è un altro lettore di docutine / Sfinge. Basato su markdown-it-py, compatibile con CommonMark.

  • Ha una {ROLE_NAME}`...`sintassi generica per i ruoli.
  • Ha una sintassi generica per le direttive con ```{DIRECTIVE_NAME} ...blocchi recintati.

In tutti i casi, dovrai inventare le estensioni di Markdown per rappresentare le direttive e i ruoli della Sfinge . Anche se potresti non averne bisogno tutti, alcuni come .. toctree::sono essenziali.
Questa penso sia la parte più difficile. reStructuredText prima che le estensioni di Sfinge fossero già più ricche di markdown. Anche il markdown fortemente esteso, come quello di Pandoc , è principalmente un sottoinsieme del set di funzionalità rST. C'è molto terreno da percorrere!

Per quanto riguarda l'implementazione, la cosa più semplice è aggiungere un costrutto generico per esprimere qualsiasi ruolo / direttiva di docutils. I candidati ovvi per l'ispirazione della sintassi sono:

  • Sintassi dell'attributo, che pandoc e alcune altre implementazioni già consentono su molti costrutti inline e block. Ad esempio `foo`{.method}-> `foo`:method:.
  • HTML / XML. Dall'approccio <span class="method">foo</span>più kludgiest di solo l'inserimento di XML interno docutils!
  • Qualche tipo di YAML per le direttive?

Ma una mappatura così generica non sarà la soluzione più markdown ... Attualmente i posti più attivi per discutere delle estensioni di markdown sono https://groups.google.com/forum/#!topic/pandoc-discuss , https: // github.com/scholmd/scholmd/

Questo significa anche che non puoi semplicemente riutilizzare un parser markdown senza estenderlo in qualche modo. Pandoc è di nuovo all'altezza della sua reputazione di coltellino svizzero di conversione di documenti supportando filte personalizzate . (In effetti, se dovessi avvicinarmi a questo, proverei a costruire un ponte generico tra lettori / trasformatori / scrittori di docutils e lettori / filtri / scrittori pandoc. È più di quello che ti serve, ma il profitto sarebbe molto più ampio della semplice sfinge / markdown.)


Un'idea folle alternativa: invece di estendere il markdown per gestire Sphinx, estendi reStructuredText per supportare (principalmente) un superset di markdown! Il bello è che sarai in grado di utilizzare qualsiasi funzionalità di Sphinx così com'è, ma di poter scrivere la maggior parte dei contenuti in markdown.

Esiste già una notevole sovrapposizione di sintassi ; in particolare la sintassi dei collegamenti è incompatibile. Penso che se aggiungi il supporto a RST per i collegamenti markdown e le ###intestazioni di stile e cambi il `backticks`ruolo predefinito in letterale e forse cambi i blocchi rientrati in letterali (i supporti RST > ...per le quotazioni di oggi), otterrai qualcosa di utilizzabile che supporta la maggior parte dei markdown .


17
Concludo per la mancanza di progressi in questo settore, il ReST potrebbe essere abbastanza buono e non sufficientemente dissimile, quindi Markdown per valere la pena di tale impresa.
Prof. Falken,

5
TLDR: utilizzare recommonmark per scrivere la documentazione Sphinx usando Markdown.
ostrokach

suggerire di aggiungere il nuovo myst-parsera questa risposta. vincerà.
Rick supporta Monica il

92

Puoi usare Markdown e reStructuredText nello stesso progetto Sphinx. Come fare questo è brevemente documentato su Leggi i documenti .

Installa recommonmark ( pip install recommonmark) e poi modifica conf.py:

from recommonmark.parser import CommonMarkParser

source_parsers = {
    '.md': CommonMarkParser,
}

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

Ho creato un piccolo progetto di esempio su Github (serra / sphinx-with-markdown) per dimostrare come (e quello) funziona. Utilizza CommonMark 0.5.4 e raccomanda 0.4.0.


4
Beni menziona questo approccio nella sua risposta molto esauriente sopra . Tuttavia, ritengo che questa domanda meriti questa semplice risposta.
Marijn,

2
È importante leggere recommonmark.readthedocs.org/en/latest/auto_structify.html , in particolare come creare un toctree e come utilizzare il eval_rstblocco recintato per inserire qualsiasi costrutto / direttiva rST.
Beni Cherniavsky-Paskin,

questo ha richiesto l'installazione di recommonmark e Commonmark
XavierCLL

1
Ottengo ImportError: cannot import name 'DocParser'Sphinx 1.4.1 in Python 3.4.3.
detly

2
@detly: ImportError è dovuto all'ultima versione di commonmark (0.6.0) che rompe la compatibilità con il raccomandazione: vedere github.com/rtfd/recommonmark/issues/24 . La soluzione:pip install commonmark==0.5.5 --upgrade
kadee,

30

Questo non usa Sphinx, ma MkDocs costruirà la tua documentazione usando Markdown. Anche io odio per primo, e finora mi sono davvero divertito con MkDocs.


5
MkDocs ha funzionato molto bene anche qui, per la documentazione per l'utente finale. Sto ancora cercando di usare il markdown nei documenti ..
Marcus Ottosson,

2
Tanto sì per questo.
jkmacc,

1
Ehi, grazie - MkDocs è fantastico! Perdo molta potenza e funzionalità rispetto a Sphinx e RST, questo è certo ... ma è incredibilmente semplice, snello e così facile e veloce da usare. Perfetto per quasi tutti i miei casi d'uso - come brevi istruzioni di installazione e alcuni tutorial di avvio rapido con alcuni esempi. Per i pochi casi, in cui ho bisogno di un sacco di codice sorgente che spiega - per esempio la documentazione di chiamata di classe e funzione - resto con Sphinx.
Bruto

Al momento della stesura di questo documento, tuttavia supporta solo 2 livelli di rientro TOC.
Wrygiel,

@wrygiel Non hai ragione: il numero di livelli TOC renderizzati dipende dal tema che stai utilizzando.
Ale

27

Aggiornamento: ora è ufficialmente supportato e documentato nei documenti Sfinge .

Sembra che un'implementazione di base sia entrata in Sphinx ma la parola non è ancora cambiata. Vedi il commento sul problema di github

installare dipendenze:

pip install commonmark recommonmark

regolare conf.py:

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

1
Se ottieni cannot import name DocParser, prova pip install commonmark==0.5.5.
Roger Dahl,

1
Il collegamento ai documenti sulla sfinge dovrebbe essere sphinx-doc.org/it/master/usage/markdown.html
Paul Brannan,

21

Markdown e ReST fanno cose diverse.

RST fornisce un modello a oggetti per lavorare con i documenti.

Markdown fornisce un modo per incidere frammenti di testo.

Sembra ragionevole voler fare riferimento ai tuoi frammenti di contenuto Markdown dal tuo progetto Sfinge, usando RST per stubare l'architettura generale delle informazioni e il flusso di un documento più grande. Lascia che il markdown faccia quello che fa, che consente agli scrittori di concentrarsi sulla scrittura di testo.

C'è un modo per fare riferimento a un dominio markdown, solo per incidere il contenuto così com'è? RST / sfinge sembra aver curato le funzionalità come toctreesenza duplicarle nel markdown.


5
"Sembra ragionevole voler fare riferimento ai tuoi frammenti di contenuto Markdown dal tuo progetto Sfinge" - questo è in realtà quello che voglio fare; Voglio includere alcuni contenuti markdown (i miei README.md) nella mia documentazione Sphinx più completa. Sai se questo è possibile?
detly


8

Sono andato con il suggerimento di Beni di usare pandoc per questo compito. Una volta installato, il seguente script converte tutti i file di markdown nella directory di origine in primi file, in modo da poter scrivere tutta la documentazione in markdown. Spero che questo sia utile per gli altri.

#!/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(' '))

1

C'è una soluzione alternativa.
Lo script sphinx-quickstart.py genera un Makefile.
Puoi facilmente invocare Pandoc dal Makefile ogni volta che desideri generare la documentazione per convertire Markdown in reStructuredText.


3
A meno che non stia facendo qualcosa di sbagliato, non è così facile sostituire ReST con Markdown. Se usi istruzioni come toctree nel file sorgente Markdown, Pandoc le cambierà in un'unica riga: .. toctree:: :maxdepth: 2 :glob:durante la trasformazione e smetteranno di funzionare. In altre parole, è impossibile usare le direttive in questo modo.
Wiktor Walc,

@WiktorWalc Non conosco molto bene il pandoc e non l'ho ancora provato, ma credo abbia senso. Oh bene. Provai. Immagino che tu possa presentare una segnalazione di bug?
the_drow,

@WiktorWalc: ..toctreenon è una sintassi Markdown valida. O scrivi l'intero documento in Markdown (e perdi le bellezze di ReSt), oppure usi ReST. Non puoi avere la tua torta e mangiarla anche tu.
Aditya,

1
solo un suggerimento: una soluzione sarebbe quella di utilizzare i filtri PandC per saltare quelle istruzioni speciali e lasciarle come nella generazione dell'output. Non sono un mago dei filtri Pandoc e aggiunge ulteriore complessità allo schema.
zmo


0

Nota che la costruzione di documentazione utilizzando Maven e integrato il supporto Sfinge + MarkDown è pienamente supportato dal seguente Maven plugin:

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>
Utilizzando il nostro sito, riconosci di aver letto e compreso le nostre Informativa sui cookie e Informativa sulla privacy.
Licensed under cc by-sa 3.0 with attribution required.