Utilisation de sphinx avec Markdown au lieu de RST


212

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?


1
Je ne connais aucune option disponible pour cela. Mais notez que RST a beaucoup plus d'options que de démarque en termes d'extensibilité. Donc, selon votre projet, cela pourrait ne pas être suffisant.
Wolph

2
Il existe un sous - ensemble de rST qui est principalement une démarque valide. Si vous détestez les listes de champs Sphinx ( :param path:etc.), voir l' extension Napoléon .
Beni Cherniavsky-Paskin

3
Si vous souhaitez documenter votre projet Python dans Markdown avec Sphinx, votez pour la demande de fonctionnalité sur bitbucket.org/birkenfeld/sphinx/issue/825/…
Colonel Panic

1
En regardant ce commentaire, il semble que vous puissiez mélanger les deux: read-the-docs.readthedocs.org/en/latest/…
Stefan van der Walt

2
Le support de base de Markdown a enfin fait son chemin dans Sphinx: voir la nouvelle réponse
Oliver Bestwalter

Réponses:


97

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 .

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 .


17
Je conclus du manque de progrès dans ce domaine, le ReST peut être juste assez bon et pas assez différent, donc Markdown pour qu'une telle entreprise en vaille la peine.
Prof.Falken

5
TLDR: utilisez recommonmark pour écrire la documentation Sphinx à l'aide de Markdown.
ostrokach

suggérer d'ajouter le nouveau myst-parserà cette réponse. ça va gagner.
Rick soutient Monica le

92

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.


4
Beni mentionne cette approche dans sa réponse très complète ci-dessus . Cependant, je pense que cette question mérite cette réponse simple.
Marijn

2
Il est important de lire recommonmark.readthedocs.org/en/latest/auto_structify.html , en particulier comment créer un toctree et comment utiliser un eval_rstbloc clôturé pour insérer n'importe quelle construction / directive rST.
Beni Cherniavsky-Paskin

cela est nécessaire pour installer recommonmark et commonmark
XavierCLL

1
Je reçois ImportError: cannot import name 'DocParser'sur Sphinx 1.4.1 sous Python 3.4.3.
detly

2
@detly: ImportError est dû à la dernière version de commonmark (0.6.0) qui rompt la compatibilité avec recommonmark: voir github.com/rtfd/recommonmark/issues/24 . La solution:pip install commonmark==0.5.5 --upgrade
kadee

30

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.


5
MkDocs a également très bien fonctionné ici, pour la documentation destinée aux utilisateurs finaux. Vous cherchez toujours à utiliser le démarque dans les docstrings ..
Marcus Ottosson

2
Tant pis pour ça.
jkmacc

1
Hé, merci - MkDocs est génial! Je perd beaucoup de puissance et de fonctionnalités par rapport au Sphinx et au RST, c'est sûr… mais il est incroyablement simple, rationalisé et si facile et rapide à utiliser. Parfait pour presque tous mes cas d'utilisation - comme des instructions d'installation courtes et un tutoriel de démarrage rapide avec quelques exemples. Pour les quelques cas, où j'ai besoin de beaucoup de code source expliquant - la documentation sur les appels de classe et de fonction ig - je reste fidèle à Sphinx.
Brutus

Au moment d'écrire ces lignes, il ne prend en charge que 2 niveaux d'indentation de la table des matières.
wrygiel

@wrygiel Vous n'avez pas tout à fait raison - le nombre de niveaux de table des matières rendus dépend du thème que vous utilisez.
Ale

27

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

1
Si vous obtenez cannot import name DocParser, essayez pip install commonmark==0.5.5.
Roger Dahl

1
Le lien vers les documents de sphinx doit être sphinx-doc.org/en/master/usage/markdown.html
Paul Brannan

21

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.


5
"Il semble raisonnable de vouloir référencer vos morceaux de contenu Markdown de votre projet sphinx" - c'est en fait ce que je veux faire; Je souhaite inclure du contenu de démarque (mon README.md) dans ma documentation Sphinx plus complète. Savez-vous si c'est possible?
detly


8

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

1

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.


3
À moins que je fasse quelque chose de mal, il n'est pas si facile de remplacer ReST par Markdown. Si vous utilisez des instructions comme toctree dans le fichier source Markdown, alors Pandoc les transformera en une seule ligne: .. toctree:: :maxdepth: 2 :glob:pendant la transformation et elles cesseront de fonctionner. En d'autres termes, il est impossible d'utiliser des directives de cette façon.
Wiktor Walc

@WiktorWalc Je ne connais pas très bien le pandoc et je ne l'ai pas vraiment essayé mais c'était logique je suppose. Tant pis. J'ai essayé. Je suppose que vous pouvez déposer un rapport de bogue?
the_drow

@WiktorWalc: ..toctreen'est pas une syntaxe Markdown valide. Soit vous écrivez le document entier dans Markdown (et perdez les subtilités de ReSt), soit vous utilisez ReST. Vous ne pouvez pas avoir votre gâteau et le manger aussi.
Aditya

1
juste un indice: une solution serait d'utiliser des filtres pandoc pour ignorer ces instructions spéciales et les laisser telles quelles dans la génération de sortie. Je ne suis pas un magicien des filtres pandoc cependant, et cela ajoute une complexité supplémentaire au schéma.
zmo


0

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>
En utilisant notre site, vous reconnaissez avoir lu et compris notre politique liée aux cookies et notre politique de confidentialité.
Licensed under cc by-sa 3.0 with attribution required.