Utilizzo della sfinge con Markdown anziché RST

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

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 .

• Non supporta ancora le direttive.

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 .

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.

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.

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']

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.

Questo è ora ufficialmente supportato: http://www.sphinx-doc.org/en/stable/markdown.html

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(' '))

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.

Ecco una nuova opzione. MyST aggiunge alcune funzionalità a Markdown che consentono a Sphinx di creare documenti come prima. https://myst-parser.readthedocs.io/en/latest/

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>