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?
:param path:
etc.), voir l' extension Napoléon .
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?
:param path:
etc.), voir l' extension Napoléon .
Réponses:
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:
Vous pouvez tricher et écrire un "analyseur" qui utilise Pandoc pour convertir le démarque en RST et le transmettre à l'analyseur RST :-).
Vous pouvez utiliser un analyseur Markdown-> XML existant et transformer le résultat (en utilisant XSLT?) En schéma docutils.
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.
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 .
```eval_rst
bloc 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.
{ROLE_NAME}`...`
syntaxe pour les rôles. ```{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:
`foo`{.method}
-> `foo`:method:
.<span class="method">foo</span>
l'approche la plus fastidieuse consistant à simplement insérer du XML interne aux docutils!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 .
myst-parser
à cette réponse. ça va gagner.
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.
eval_rst
bloc clôturé pour insérer n'importe quelle construction / directive rST.
ImportError: cannot import name 'DocParser'
sur Sphinx 1.4.1 sous Python 3.4.3.
pip install commonmark==0.5.5 --upgrade
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']
cannot import name DocParser
, essayez pip install commonmark==0.5.5
.
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 toctree
sans les dupliquer dans le démarque.
README.md
) dans ma documentation Sphinx plus complète. Savez-vous si c'est possible?
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.
.. 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.
..toctree
n'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.
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>