Usar esfinge con Markdown en lugar de RST

Odio RST pero amo a la esfinge. ¿Hay alguna forma en que la esfinge lea Markdown en lugar de reStructuredText?

La forma "adecuada" de hacerlo sería escribir un analizador docutils para rebajar . (Además de una opción Sphinx para elegir el analizador sintáctico). La belleza de esto sería el soporte instantáneo para todos los formatos de salida docutils (pero es posible que no le importe, ya que existen herramientas de reducción similares para la mayoría). Formas de abordar eso sin desarrollar un analizador desde cero:

1. Podrías hacer trampa y escribir un "analizador" que usa Pandoc para convertir Markdown a RST y pasarlo al analizador RST :-).

2. Puede usar un analizador Markdown-> XML existente y transformar el resultado (¿usando XSLT?) En el esquema docutils.

3. Podría tomar un analizador de reducción de python existente que le permita definir un renderizador personalizado y hacer que construya el árbol de nodos docutils.

4. Podría bifurcar el lector RST existente, eliminar todo lo irrelevante para rebajar y cambiar las diferentes sintaxis ( esta comparación podría ayudar) ...
   EDITAR: No recomiendo esta ruta a menos que esté preparado para probarla. Markdown ya tiene demasiados dialectos sutilmente diferentes y esto probablemente resultará en otro ...

ACTUALIZACIÓN: https://github.com/sgenoud/remarkdown es un lector de rebajas para docutils. No tomó ninguno de los accesos directos anteriores, pero utiliza una gramática PEG de perejil inspirada en la reducción de clavijas .

• Todavía no admite directivas.

ACTUALIZACIÓN: https://github.com/readthedocs/recommonmark y es otro lector de docutils, compatible de forma nativa con ReadTheDocs. Derivado del comentario, pero utiliza el analizador CommonMark-py .

• Se puede convertir específicos sintaxis más o menos natural de rebajas a estructuras apropiadas por ejemplo, lista de enlaces a un toctree. * No tiene sintaxis nativa genérica para roles.
• Admite la incorporación de cualquier contenido rST, incluidas las directivas, con un ```eval_rstbloque vallado y una abreviatura de las directivas DIRECTIVE_NAME:: ....

ACTUALIZACIÓN : MyST es otro lector de docutins / Sphinx. Basado en markdown-it-py, compatible con CommonMark.

• Tiene una {ROLE_NAME}`...`sintaxis genérica para roles.
• Tiene una sintaxis genérica para directivas con ```{DIRECTIVE_NAME} ...bloques vallados.

En todos los casos, deberá inventar extensiones de Markdown para representar las directivas y roles de Sphinx . Si bien es posible que no los necesite a todos, algunos .. toctree::son esenciales.
Esto creo que es la parte más difícil. reStructuredText antes de las extensiones Sphinx ya era más rico que Markdown. Incluso la rebaja muy extendida, como la de Pandoc , es principalmente un subconjunto del conjunto de características rST. ¡Eso es mucho terreno para cubrir!

En cuanto a la implementación, lo más fácil es agregar una construcción genérica para expresar cualquier rol / directiva docutils. Los candidatos obvios para la inspiración de sintaxis son:

• Sintaxis de atributo, que pandoc y algunas otras implementaciones ya permiten en muchas construcciones en línea y en bloque. Por ejemplo `foo`{.method}-> `foo`:method:.
• HTML / XML. ¡Desde <span class="method">foo</span>el enfoque más difícil de insertar simplemente docutils XML interno!
• ¿Algún tipo de YAML para directivas?

Pero tal mapeo genérico no será la solución más markdown-ish ... Actualmente, los lugares más activos para discutir las extensiones de markdown son https://groups.google.com/forum/#!topic/pandoc-discuss , https: // github.com/scholmd/scholmd/

Esto también significa que no puede simplemente reutilizar un analizador de reducción sin extenderlo de alguna manera. Pandoc vuelve a estar a la altura de su reputación como la navaja suiza de conversión de documentos al admitir filtros personalizados . (De hecho, si tuviera que abordar esto, trataría de construir un puente genérico entre docutils lectores / transformadores / escritores y lectores / filtros / escritores de pandoc. Es más de lo que necesita, pero la recompensa sería mucho más amplia que solo sphinx / reducción.)

Idea loca alternativa: en lugar de extender Markdown para manejar Sphinx, extienda reStructuredText para soportar (principalmente) un superconjunto de Markdown. La belleza es que podrá usar cualquier característica de Sphinx tal cual, pero podrá escribir la mayoría del contenido en el descuento.

Ya existe una considerable superposición de sintaxis ; más notablemente, la sintaxis de enlace es incompatible. Creo que si agrega soporte a RST para enlaces de rebajas y ###encabezados de estilo, y cambia la `backticks`función predeterminada a literal, y tal vez cambia los bloques sangrados a significar literal (RST admite > ...citas hoy en día), obtendrá algo utilizable que admite la mayoría de rebajas .

Puede usar Markdown y reStructuredText en el mismo proyecto Sphinx. Cómo hacer esto está sucintamente documentado en Read The Docs .

Instale recommonmark ( pip install recommonmark) y luego edite conf.py:

from recommonmark.parser import CommonMarkParser

source_parsers = {
    '.md': CommonMarkParser,
}

source_suffix = ['.rst', '.md']

He creado un pequeño proyecto de ejemplo en Github (serra / sphinx-with-markdown) que demuestra cómo (y eso) funciona. Utiliza CommonMark 0.5.4 y recommonmark 0.4.0.

Esto no usa Sphinx, pero MkDocs construirá su documentación usando Markdown. También odio primero, y realmente he disfrutado MkDocs hasta ahora.

Actualización: esto ahora está oficialmente respaldado y documentado en los documentos de sphinx .

Parece que una implementación básica ha llegado a Sphinx, pero aún no se ha corrido la voz. Ver comentario de problema de github

instalar dependencias:

pip install commonmark recommonmark

ajustar conf.py:

source_parsers = {
    '.md': 'recommonmark.parser.CommonMarkParser',
}
source_suffix = ['.rst', '.md']

Markdown y ReST hacen cosas diferentes.

RST proporciona un modelo de objetos para trabajar con documentos.

Markdown proporciona una forma de grabar fragmentos de texto.

Parece razonable querer hacer referencia a los fragmentos de contenido de Markdown de su proyecto de esfinge, utilizando RST para eliminar la arquitectura general de la información y el flujo de un documento más grande. Deje que Markdown haga lo que hace, que es permitir a los escritores centrarse en escribir texto.

¿Hay alguna manera de hacer referencia a un dominio de rebaja, solo para grabar el contenido tal como está? RST / sphinx parece haberse ocupado de características como toctreesin duplicarlas en el descuento.

Esto ahora es oficialmente compatible: http://www.sphinx-doc.org/en/stable/markdown.html

Seguí la sugerencia de Beni de usar pandoc para esta tarea. Una vez instalado, el siguiente script convertirá todos los archivos de rebajas en el directorio de origen a los primeros archivos, de modo que pueda escribir toda su documentación en rebajas. Espero que esto sea útil para otros.

#!/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(' '))

Hay una solución alternativa.
El script sphinx-quickstart.py genera un Makefile.
Puede invocar fácilmente Pandoc desde el Makefile cada vez que desee generar la documentación para convertir Markdown a reStructuredText.

Aquí hay una nueva opción. MyST agrega algunas características a Markdown que permiten a Sphinx crear documentos como lo hace primero. https://myst-parser.readthedocs.io/en/latest/

Tenga en cuenta que la documentación de construcción usando maven y el soporte integrado de Sphinx + MarkDown es totalmente compatible con el siguiente complemento maven:

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>