Utilisation de sphinx avec Markdown au lieu de RST
Je déteste la TVD mais j'aime le sphinx. Existe-t-il un moyen pour sphinx de lire markdown au lieu de reStructuredText?
La "bonne" façon de faire serait d'écrire un analyseur de docutils pour markdown. (Plus une option Sphinx pour choisir l'analyseur.) L'avantage de ceci serait un support instantané de tous les formats de sortie de docutils (mais vous ne vous en souciez peut-être pas, car des outils de démarquage similaires existent déjà pour la plupart). Façons d’aborder cela sans développer un analyseur syntaxique à partir de zéro:
Vous pouvez tricher et écrire un "analyseur" qui utilise Pandoc pour convertir le démarquage en RST et le transmettre à l'analyseur RST :-).
Vous pouvez utiliser un analyseur syntaxique existant -> XML et transformer le résultat (à l'aide de XSLT?) En schéma docutils.
Vous pourriez prendre un existant python) qui vous permet de définir un moteur de rendu personnalisé et de le faire construire une arborescence de nœuds docutils.
Vous pouvez découper le lecteur RST existant, extraire tout ce qui n'est pas pertinent pour démarquer et modifier les différentes syntaxes ( cette comparaison pourrait aider) ...
EDIT: Je ne recommande pas cette route à moins d’être prête à la tester. Markdown a déjà trop de dialectes subtilement différents, ce qui entraînera probablement un autre encore ...
UPDATE: https://github.com/sgenoud/remarkdown est un lecteur de démarques pour docutils. Il n'a pris aucun des raccourcis ci-dessus, mais utilise une grammaire de type Persil inspirée de peg-markdown . Pas encore directives de support.
UPDATE: https://github.com/rtfd/recommonmark et est un autre lecteur de docutils, pris en charge de manière native sur ReadTheDocs. de remarquedown mais utilise l’analyseur CommonMark-py . Ne supporte pas les directives, mais peut convertir Syntaxes de Markdown plus ou moins naturelles en structures appropriées, par ex. liste des liens vers un toctree. Pour les autres besoins, un ```eval_rst bloc isolé vous permet d’incorporer n’importe quelle directive rST.
Dans tous les cas , vous devrez inventer des extensions de Markdown pour représenter directives et rôles Sphinx . Bien que vous n'ayez peut-être pas tous besoin d'eux, certains, comme .. toctree:: sont essentiels.
Je pense que c'est la partie la plus difficile. reStructuredText avant les extensions Sphinx était déjà plus riche que markdown. Même un démarquage très étendu, tel que pandoc's , est principalement un sous-ensemble de fonctionnalités RST. C'est beaucoup de terrain à couvrir!
En ce qui concerne l'implémentation, le plus simple est d'ajouter une construction générique pour exprimer tout rôle/directive de docutils. Les candidats évidents pour l'inspiration syntaxique sont:
- La syntaxe d'attribut, que pandoc et d'autres implémentations autorisent déjà pour de nombreuses constructions en ligne et par blocs. Par exemple
`foo`{.method}->`foo`:method:. - HTML/XML. De
<span class="method">foo</span>à la plus simple approche consistant à insérer du XML interne à Docutils! - Une sorte de YAML pour les directives?
Mais un tel mappage générique ne sera pas la solution la plus mark-ish ... Les endroits actuellement les plus actifs pour discuter des extensions de markdown sont https://groups.google.com/forum/#!topic/pandoc-discuss , https://github.com/scholmd/scholmd/
Cela signifie également que vous ne pouvez pas simplement réutiliser un analyseur de démarques sans le prolonger. Pandoc est à nouveau à la hauteur de sa réputation de couteau suisse de conversion de documents par support filtes personnalisées . (En fait, si je devais aborder cette question, j'essaierais de créer un pont générique entre les lecteurs/transformateurs/écrivains de docutils et les lecteurs/filtres/écrivains de pandoc. réduction.)
Idée folle alternative: au lieu d’allonger le démarquage pour gérer Sphinx, étendez reStructuredText pour prendre en charge (principalement) un sur-ensemble de démarcation! La beauté, c’est que vous serez capable d’utiliser toutes les fonctionnalités de Sphinx telles quelles, tout en étant capable d’écrire la plupart du contenu dans Markdown.
Il y a déjà chevauchement considérable de la syntaxe ; notamment la syntaxe de lien est incompatible. Je pense que si vous ajoutez le support à la TVD pour les liens de démarcation, et ###- style en-têtes, et change la valeur par défaut `backticks` rôle en littéral, et peut-être changer les blocs indentés en signification littérale (RST prend en charge > ... pour les citations de nos jours), vous obtiendrez quelque chose d’utilisable prenant en charge la plupart des démarques.
Vous pouvez utiliser Markdown et reStructuredText dans le même projet Sphinx. Comment faire cela est documenté succinctement sur Read The Docs .
Installez recommonmark (pip install recommonmark) puis éditez conf.py:
from recommonmark.parser import CommonMarkParser
source_parsers = {
'.md': CommonMarkParser,
}
source_suffix = ['.rst', '.md']
J'ai créé un petit exemple de projet sur Github (serra/sphinx-with-markdown) démontrant comment (et cela) cela fonctionne. Il utilise CommonMark 0.5.4 et recommonmark 0.4.0.
Cela n'utilise pas Sphinx, mais MkDocs construira votre documentation à l'aide de Markdown. Je déteste aussi d’abord et j’ai vraiment apprécié MkDocs jusqu’à présent.
Mise à jour: ceci est maintenant officiellement supporté et documenté dans sphinx docs .
Il semble qu'une implémentation de base ait été introduite dans Sphinx, mais Word n'est pas encore disponible. Voir le commentaire du problème github
installer des dépendances:
pip install commonmark recommonmark
régler conf.py:
source_parsers = {
'.md': 'recommonmark.parser.CommonMarkParser',
}
source_suffix = ['.rst', '.md']
Markdown et ReST font des choses différentes.
RST fournit un modèle objet pour travailler avec des documents.
Markdown fournit un moyen de graver des bouts de texte.
Il semble raisonnable de vouloir référencer vos éléments de contenu Markdown de votre projet sphinx, en utilisant RST pour décomposer l'architecture globale de l'information et le flux d'un document plus volumineux. Laissez Markdown faire ce qu'il fait, c'est-à-dire permettre aux auteurs de se concentrer sur la rédaction de texte.
Existe-t-il un moyen de référencer un domaine de démarquage, juste pour graver le contenu tel quel? RST/sphinx semble s’être occupé de fonctionnalités telles que toctree sans les dupliquer dans le démarquage.
Je suis allé avec la suggestion de Beni d'utiliser Pandoc pour cette tâche. Une fois installé, le script suivant convertira tous les fichiers markdown du répertoire source en premiers fichiers, de sorte que vous pourrez simplement écrire toute votre documentation dans markdown. J'espère que cela est utile pour les autres.
#!/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(' '))
Ceci est maintenant officiellement supporté: http://www.sphinx-doc.org/en/stable/markdown.html
Il y a une solution de contournement.
Le script sphinx-quickstart.py génère un fichier Makefile.
Vous pouvez facilement appeler Pandoc à partir du Makefile chaque fois que vous souhaitez générer la documentation afin de convertir Markdown en texte reStructuredText.
Notez que la documentation de construction utilisant maven et la prise en charge intégrée de Sphinx + MarkDown est entièrement prise en charge par le plugin maven suivant:
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>