À l’aide de sphinx avec Markdown au lieu de la TVD

Question

Je déteste la TVD mais amour sphinx. Est il un moyen que sphinx lit démarque au lieu de reStructuredText ?

Answer 1

La "bonne" façon de le faire serait d'écrire un docutils analyseur de markdown. (Plus un Sphinx option pour choisir l'analyseur.) La beauté de cet instant de soutien pour tous les docutils formats de sortie (mais vous ne pourriez pas de soins à ce sujet, comme similaires démarque des outils existent déjà pour la plupart). Façons de l'aborder sans le développement d'un analyseur à partir de zéro:

• Vous pouvez tricher et d'écrire un "parser" qui utilise Pandoc pour convertir démarque à la TVD et passer le premier analyseur :-).

• Vous pouvez utiliser une markdown->analyseur XML et transformer le résultat (à l'aide de XSLT?) à la docutils schéma.

• Vous pourriez prendre un certain existant python markdown analyseur qui vous permet de définir votre propre moteur de rendu et de faire construire docutils nœud de l'arbre.

• Vous pourriez fourche existants TVD lecteur, de l'extraction des tout pas pertinente pour les démarques et de changer les différentes syntaxes (cette comparaison peut aider)...
  EDIT: je ne recommande pas cette route, sauf si vous êtes prêt à fortement de le tester. Markdown a déjà trop de subtilement différents dialectes et ce sera probablement résultat en encore un autre un...

Mise à JOUR: https://github.com/sgenoud/remarkdown est un markdown reader pour docutils. Il n'a pas fallu un des au-dessus des raccourcis, mais utilise un Persil PEG grammaire inspirée par peg-markdown. Qui n'a pas encore de support de directives.

---

Dans tous les cas, vous aurez besoin d'inventer des extensions de Markdown pour représenter les Sphinx les directives et les rôles. Bien que vous n'ayez pas tous d'entre eux, certains l'aiment .. toctree:: sont essentiels [*].
Je pense que c'est la partie la plus difficile. reStructuredText avant le Sphinx extensions était déjà plus riche que markdown. Même fortement étendu markdown, tels que pandoc est, est le plus souvent un sous-ensemble de la tvd. C'est beaucoup de terrain à couvrir!

Mise en œuvre-sage, le plus simple est d'ajouter un générique de construire à exprimer toute docutils rôle/directive. Les candidats évidents pour la syntaxe d'inspiration sont:

• La syntaxe d'attribut, qui pandoc et d'autres implémentations permettent déjà sur de nombreux en ligne et de bloquer les constructions. Par exemple `foo`{.method} -> `foo`:method:.
• HTML/XML. D' <span class="method">foo</span> de la kludgiest approche de la juste de l'insertion docutils XML interne!
• Une sorte de YAML pour les directives?

Mais tel un générique de cartographie ne sera pas la plus markdown-ish solution... Actuellement, la plupart des actifs lieux pour discuter de démarque extensions sont https://groups.google.com/forum/#!topic/pandoc-discuter, https://github.com/scholmd/scholmd/

Cela signifie également que vous ne pouvez pas réutiliser un abattement de l'analyseur sans l'étendre en quelque sorte. Pandoc de nouveau à la hauteur de sa réputation comme le couteau suisse de la conversion de document par un soutien personnalisé filtes. (En fait, si j'étais à l'approche de ce que j'avais essayer de construire un générique pont entre docutils lecteurs/transformateurs/écrivains et pandoc lecteurs/filtres/écrivains. C'est plus que vous avez besoin, mais le gain serait beaucoup plus large que juste sphinx/markdown.)

---

Alternative idée folle: au lieu de l'étendre markdown pour gérer les Sphinx, étendre reStructuredText à l'appui (pour la plupart) un sur-ensemble de démarques! La beauté est que vous serez en mesure d'utiliser toutes les Sphinx caractéristiques que-est, pourtant, être capable d'écrire plus de contenu en markdown.

Il est déjà considérable de la syntaxe de chevauchement; plus particulièrement lien syntaxe est incompatible. Je pense que si vous ajouter la prise en charge de la TVD pour les démarques des liens, et ###-style-têtes, et de modifier la valeur par défaut `backticks` rôle de, littérale et peut-être changer en retrait des blocs de dire littérale (TVD soutient > ... pour les citations de nos jours), vous obtiendrez quelque chose d'utilisable qui prend en charge la plupart des démarques.

Answer 2

Il n’utilise pas de Sphinx, mais MkDocs s’appuiera votre documentation en utilisant Markdown. Aussi, je déteste la TVD et ont vraiment apprécié MkDocs jusqu'à présent.

Answer 3

Markdown de Repos et de faire des choses différentes.

TVD fournit un modèle d'objet pour travailler avec des documents.

Markdown fournit un moyen de graver des morceaux de texte.

Il semble raisonnable d'en souhaitez référencer votre bits de Markdown contenu de votre sphinx projet, en utilisant d'abord à talon de l'ensemble de l'architecture de l'information et du flux d'un document plus volumineux. Laissez markdown faire ce qu'il fait, qui est de permettre aux auteurs de se concentrer sur l'écriture d'un texte.

Est-il un moyen de faire référence à un abattement de domaine, juste pour graver le contenu-est? TVD/sphinx semble avoir pris soin de fonctionnalités comme l' toctree sans les dupliquer en markdown.

Answer 4

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