Usando la esfinge con Markdown en lugar de RST

Odio RST pero amo la esfinge. ¿Hay alguna forma en que la esfinge lea el margen de reducción en lugar de reStructuredText?

La forma “correcta” de hacerlo sería escribir un analizador de docutils para el descuento. (Más una opción de Sphinx para elegir el analizador). La belleza de esto sería el soporte instantáneo para todos los formatos de salida de docutils (pero puede que no te importe, ya que la mayoría de las herramientas similares de reducción de precios ya existen). Formas de abordar eso sin desarrollar un analizador desde cero:

  • Podría hacer trampa y escribir un “analizador” que utiliza Pandoc para convertir markdown a RST y pasarlo al analizador de RST :-).

  • Puede usar un markdown existente -> analizador XML y transformar el resultado (¿usando XSLT?) Al esquema de docutils.

  • Podría tomar algún analizador de bajada de Python existente que le permita definir un renderizador personalizado y hacer que compile el árbol de nodos docutils.

  • Podría desembolsar el lector RST existente, eliminando todo lo irrelevante para reducir y cambiar las diferentes syntax ( esta comparación podría ayudar) …
    EDITAR: No recomiendo esta ruta a menos que esté preparado para probarlo en gran medida. Markdown ya tiene demasiados dialectos sutilmente diferentes y esto probablemente resultará en uno más …

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 peg-markdown . Aún no soporta directivas.

ACTUALIZACIÓN: https://github.com/rtfd/recommonmark y es otro lector de docutils, soportado de forma nativa en ReadTheDocs. Derivado de remarcado pero utiliza el analizador CommonMark-py . No admite directivas, pero puede convertir syntax de Markdown más o menos naturales a estructuras apropiadas, por ejemplo, una lista de enlaces a un toctree. Para otras necesidades, un bloque cercado ```eval_rst permite incrustar cualquier directiva rST.


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 todos, algunos como .. toctree:: son esenciales.
Esto creo que es la parte más difícil. reStructuredText antes de las extensiones de Sphinx ya era más rico que markdown. Incluso una 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 express cualquier rol / directiva de docutils. Los candidatos obvios para la inspiración de la syntax son:

  • Sintaxis de atributos, que pandoc y algunas otras implementaciones ya permiten en muchas construcciones en línea y de bloque. Por ejemplo `foo`{.method} -> `foo`:method:
  • HTML / XML. ¡Desde foo hasta el enfoque más simple de solo insertar los documentos internos de XML!
  • ¿Algún tipo de YAML para directivas?

Pero tal asignación genérica no será la solución más de reducción de marca … Actualmente, los lugares más activos para analizar las extensiones de reducción de velocidad son https://groups.google.com/forum/#!topic/pandoc-discuss , https: // github.com/scholmd/scholmd/

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


Idea loca alternativa: en lugar de extender el descuento para manejar Sphinx, ¡extienda reStructuredText para apoyar (en su mayoría) un superconjunto de descuento! La belleza es que podrás usar cualquier característica de Sphinx tal como está, pero podrás escribir la mayoría del contenido en markdown.

Ya existe una considerable superposición de syntax ; más notablemente la syntax de enlaces es incompatible. Creo que si agrega soporte a RST para los enlaces de reducción y encabezados de estilo ### , y cambia el rol predeterminado de `backticks` a literal, y tal vez cambie los bloques con sangría para que signifique literal (RST admite > ... para las citas de hoy en día), obtendrás algo utilizable que soporta la mayoría de las rebajas.

Puede usar Markdown y reStructuredText en el mismo proyecto Sphinx. La forma de hacer esto se documenta sucintamente en Leer los documentos .

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 recomonmark 0.4.0.

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

Actualización: esto ahora está oficialmente soportado y documentado en los documentos de la esfinge .

Parece que una implementación básica se ha abierto camino en Sphinx pero aún no se ha corrido la voz. Ver el comentario de Github

dependencias de instalación:

 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 objeto para trabajar con documentos.

Markdown proporciona una forma de grabar bits de texto.

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

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

Fui con la sugerencia de Beni de usar pandoc para esta tarea. Una vez instalado, el siguiente script convertirá todos los archivos markdown en el directorio de origen en primeros archivos, para que pueda escribir toda su documentación en markdown. 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(' ')) 

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

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

Tenga en cuenta que la siguiente documentación de Maven es compatible con Maphin y con la compatibilidad integrada con MarkDown:

https://trustin.github.io/sphinx-maven-plugin/index.html

  kr.motd.maven sphinx-maven-plugin 1.6.1  ${project.build.directory}/docs    package  generate