Utilisation de sphinx avec Markdown au lieu de RST

Je déteste la TVD mais j'adore le sphinx. Existe-t-il un moyen pour le sphinx de lire le démarque au lieu de reStructuredText?

La façon "appropriée" de le faire serait d'écrire un analyseur de docutils pour le démarquage . (Plus une option Sphinx pour choisir l'analyseur.) La beauté de cela serait la prise en charge instantanée de tous les formats de sortie de docutils (mais vous pourriez ne pas vous en soucier, car des outils de démarque similaires existent déjà pour la plupart). Façons d'aborder cela sans développer un analyseur à partir de zéro:

1. Vous pouvez tricher et écrire un "analyseur" qui utilise Pandoc pour convertir le démarque en RST et le transmettre à l'analyseur RST :-).

2. Vous pouvez utiliser un analyseur Markdown-> XML existant et transformer le résultat (en utilisant XSLT?) En schéma docutils.

3. Vous pouvez prendre un analyseur de Markdown Python existant qui vous permet de définir un rendu personnalisé et de le faire construire l'arborescence des nœuds docutils.

4. Vous pouvez bifurquer le lecteur RST existant, extraire tout ce qui n'est pas pertinent pour le démarquage et changer les différentes syntaxes (
   ce qui n'est pas cette comparaison pourrait aider) ... EDIT: Je ne recommande pas cette route à moins que vous ne soyez prêt à le tester intensivement. Markdown a déjà trop de dialectes subtilement différents et cela en résultera probablement en un autre ...

MISE À JOUR: https://github.com/sgenoud/remarkdown est un lecteur de démarque pour docutils. Il n'a pris aucun des raccourcis ci-dessus mais utilise un grammaire Parsley PEG inspirée du marquage des chevilles .

• Ne prend pas encore en charge les directives.

MISE À JOUR: https://github.com/readthedocs/recommonmark et est un autre lecteur de docutils, nativement pris en charge sur ReadTheDocs. Dérivé de la remarque mais utilise le analyseur CommonMark-py .

• Il peut convertir des syntaxes Markdown plus ou moins naturelles spécifiques en structures appropriées, par exemple une liste de liens vers un toctree. * N'a pas de syntaxe native générique pour les rôles.
• Prend en charge l'intégration de tout contenu rST, y compris les directives, avec un ```eval_rstbloc clôturé ainsi qu'un raccourci pour les directives DIRECTIVE_NAME:: ....

MISE À JOUR : MyST est encore un autre lecteur de docutins / Sphinx. Basé sur markdown-it-py, compatible CommonMark.

• A un générique {ROLE_NAME}`...` syntaxe pour les rôles.
• A une syntaxe générique pour les directives avec ```{DIRECTIVE_NAME} ...des blocs clôturés.

Dans tous les cas, vous devrez inventer des extensions de Markdown pour représenter les directives et les rôles Sphinx . Bien que vous n'ayez pas besoin de tous, certains .. 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 une démarque fortement étendue, comme pandoc , est principalement un sous-ensemble de fonctionnalités rST. C'est beaucoup de terrain à parcourir!

Au niveau de l'implémentation, la chose la plus simple est d'ajouter une construction générique pour exprimer n'importe quel rôle / directive docutils. Les candidats évidents pour l'inspiration syntaxique sont:

• Syntaxe d'attribut, que pandoc et certaines autres implémentations autorisent déjà sur de nombreuses constructions en ligne et en bloc. Par exemple`foo`{.method} -> `foo`:method:.
• HTML / XML. De<span class="method">foo</span> l'approche la plus fastidieuse consistant à simplement insérer du XML interne aux docutils!
• Une sorte de YAML pour les directives?

Mais un tel mappage générique ne sera pas la solution la plus démarquée ... Actuellement, les endroits les plus actifs pour discuter des extensions de démarque 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 l'étendre d'une manière ou d'une autre. Pandoc est à la hauteur de sa réputation de couteau suisse de conversion de documents en prenant en charge les fichiers personnalisés . (En fait, si je m'approchais de cela, j'essaierais de construire un pont générique entre les lecteurs / transformateurs / écrivains docutils et les lecteurs / filtres / écrivains pandoc. C'est plus que ce dont vous avez besoin mais le gain serait beaucoup plus large que le simple sphinx / réduction.)

Idée folle alternative: au lieu d'étendre le démarque pour gérer Sphinx, étendez reStructuredText pour prendre en charge (principalement) un surensemble de démarque! La beauté est que vous pourrez utiliser toutes les fonctionnalités de Sphinx telles quelles, tout en étant capable d'écrire la plupart du contenu dans le démarque.

Il existe déjà un chevauchement syntaxique considérable ; notamment la syntaxe des liens est incompatible. Je pense que si vous ajoutez la prise en charge à RST pour les liens de démarque et les en- ###têtes de style, et changez le `backticks`rôle par défaut en littéral, et peut-être changez les blocs en retrait pour signifier littéral (RST prend en charge les > ...citations de nos jours), vous obtiendrez quelque chose utilisable qui prend en charge la plupart des démarques .

Vous pouvez utiliser Markdown et reStructuredText dans le même projet Sphinx. La procédure à suivre est succinctement documentée dans Read The Docs .

Installez recommonmark ( pip install recommonmark) puis modifiez 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 avec markdown) démontrant comment (et que) cela fonctionne. Il utilise CommonMark 0.5.4 et recommonmark 0.4.0.

Cela n'utilise pas Sphinx, mais MkDocs construira votre documentation en utilisant Markdown. Je déteste aussi le premier et j'ai vraiment apprécié MkDocs jusqu'à présent.

Mise à jour: ceci est désormais officiellement pris en charge et documenté dans la documentation de sphinx .

Il semble qu'une implémentation de base ait fait son chemin dans Sphinx, mais le mot n'a pas encore circulé. Voir le commentaire du problème github

installer les dépendances:

pip install commonmark recommonmark

ajuster 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 d'objet pour travailler avec des documents.

Markdown fournit un moyen de graver des morceaux de texte.

Il semble raisonnable de vouloir référencer vos morceaux de contenu Markdown de votre projet sphinx, en utilisant RST pour bloquer l'architecture globale des informations et le flux d'un document plus volumineux. Laissez Markdown faire ce qu'il fait, ce qui permet aux écrivains de se concentrer sur l'écriture de texte.

Existe-t-il un moyen de référencer un domaine de démarque, juste pour graver le contenu tel quel? RST / sphinx semble avoir pris en charge des fonctionnalités comme toctreesans les dupliquer dans le démarque.

Ceci est désormais officiellement pris en charge: http://www.sphinx-doc.org/en/stable/markdown.html

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 de démarques du répertoire source en premiers fichiers, afin que vous puissiez simplement écrire toute votre documentation dans les démarques. J'espère que cela sera 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(' '))

Il existe une solution de contournement.
Le script sphinx-quickstart.py génère un Makefile.
Vous pouvez facilement appeler Pandoc à partir du Makefile chaque fois que vous souhaitez générer la documentation afin de convertir Markdown en reStructuredText.

Voici une nouvelle option. MyST ajoute quelques fonctionnalités à Markdown qui permettent à Sphinx de créer des documents comme le fait le premier. https://myst-parser.readthedocs.io/en/latest/

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 plug-in 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>