Odio RST ma amo la sfinge. C'è un modo in cui la sfinge legge markdown invece di reStructuredText?
:param path:
ecc.), Vedi l' estensione di Napoleone .
Odio RST ma amo la sfinge. C'è un modo in cui la sfinge legge markdown invece di reStructuredText?
:param path:
ecc.), Vedi l' estensione di Napoleone .
Risposte:
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:
È possibile imbrogliare e scrivere un "parser" che utilizza Pandoc per convertire markdown in RST e passarlo al parser RST :-).
È possibile utilizzare un parser markdown esistente-> XML e trasformare il risultato (usando XSLT?) Nello schema docutils.
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.
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 .
```eval_rst
blocco 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.
{ROLE_NAME}`...`
sintassi generica per i ruoli. ```{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:
`foo`{.method}
-> `foo`:method:
.<span class="method">foo</span>
più kludgiest di solo l'inserimento di XML interno docutils!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 .
myst-parser
a questa risposta. vincerà.
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.
eval_rst
blocco recintato per inserire qualsiasi costrutto / direttiva rST.
ImportError: cannot import name 'DocParser'
Sphinx 1.4.1 in Python 3.4.3.
pip install commonmark==0.5.5 --upgrade
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']
cannot import name DocParser
, prova pip install commonmark==0.5.5
.
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 toctree
senza duplicarle nel markdown.
README.md
) nella mia documentazione Sphinx più completa. Sai se questo è possibile?
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.
.. toctree:: :maxdepth: 2 :glob:
durante la trasformazione e smetteranno di funzionare. In altre parole, è impossibile usare le direttive in questo modo.
..toctree
non è 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.
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>