Usar esfinge con Markdown en lugar de RST

212

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

digi604
fuente
1
No conozco ninguna opción disponible para esto. Pero tenga en cuenta que RST tiene muchas más opciones que el descuento en términos de extensibilidad. Entonces, dependiendo de su proyecto, podría no ser suficiente.
Wolph
2
Hay un subconjunto de rST que es principalmente una reducción válida. Si odia las listas de campos de Sphinx ( :param path:etc.), vea la extensión de Napoleón .
Beni Cherniavsky-Paskin
3
Si desea documentar su proyecto de Python en Markdown con Sphinx, vote por la solicitud de función en bitbucket.org/birkenfeld/sphinx/issue/825/…
Coronel Panic el
1
Al mirar este comentario, parece que puedes mezclar los dos: read-the-docs.readthedocs.org/en/latest/…
Stefan van der Walt
2
El soporte básico de Markdown finalmente ha llegado a Sphinx: ver nueva respuesta
Oliver Bestwalter

Respuestas:

97

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 .

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 .

Beni Cherniavsky-Paskin
fuente
17
Concluyo por la falta de progreso en esta área, el ReST puede ser lo suficientemente bueno y no lo suficientemente diferente como para que Markdown valga la pena.
Prof. Falken
55
TLDR: use recommonmark para escribir la documentación de Sphinx usando Markdown.
ostrokach
sugiera agregar lo nuevo myst-parsera esta respuesta. va a ganar
Rick apoya a Mónica el
92

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.

Marijn
fuente
44
Beni menciona este enfoque en su muy completa respuesta anterior . Sin embargo, creo que esta pregunta merece esta respuesta simple.
Marijn
2
Es importante leer recommonmark.readthedocs.org/en/latest/auto_structify.html , especialmente cómo crear un toctree y cómo usar un eval_rstbloque vallado para insertar cualquier construcción / directiva rST.
Beni Cherniavsky-Paskin
esto se requiere para instalar recommonmark y commonmark
XavierCLL
1
Me meto ImportError: cannot import name 'DocParser'en Sphinx 1.4.1 bajo Python 3.4.3.
desvío
2
@detly: ImportError se debe a la última versión de commonmark (0.6.0) que rompe la compatibilidad con recommonmark: consulte github.com/rtfd/recommonmark/issues/24 . La solución:pip install commonmark==0.5.5 --upgrade
kadee
30

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

jkmacc
fuente
55
MkDocs también ha funcionado muy bien aquí, para la documentación del usuario final. Todavía estoy buscando usar Markdown dentro de las cadenas de documentos ..
Marcus Ottosson
2
Tanto sí por esto.
jkmacc
1
Hola, gracias. ¡ MkDocs es increíble! Pierdo mucha potencia y funciones en comparación con Sphinx y RST, eso es seguro ... pero es increíblemente sencillo, simplificado y muy fácil y rápido de usar. Perfecto para casi todos mis casos de uso, como instrucciones breves de instalación y algunos tutoriales de inicio rápido con algunos ejemplos. Sin embargo, para los pocos casos en los que necesito una gran cantidad de explicaciones del código fuente (documentación de llamadas de funciones y clases ig), sigo con Sphinx.
Brutus
Al momento de escribir esto, solo admite 2 niveles de sangría TOC.
wrygiel
@wrygiel No tiene toda la razón: la cantidad de niveles de TOC representados depende del tema que esté utilizando.
Ale
27

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']
Oliver Bestwalter
fuente
1
Si consigues cannot import name DocParser, inténtalo pip install commonmark==0.5.5.
Roger Dahl el
1
El enlace a los documentos de sphinx debe ser sphinx-doc.org/en/master/usage/markdown.html
Paul Brannan
21

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.

hacia el oeste
fuente
55
"Parece razonable querer hacer referencia a sus fragmentos de contenido de Markdown de su proyecto de esfinge"; esto es realmente lo que quiero hacer; Quiero incluir algún contenido de descuento (mi README.md) en mi documentación más completa de Sphinx. ¿Sabes si esto es posible?
detly
8

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(' '))
igniteflow
fuente
1

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.

the_drow
fuente
3
A menos que esté haciendo algo mal, no es tan fácil reemplazar ReST con Markdown. Si usa instrucciones como toctree en el archivo fuente de Markdown, Pandoc las cambiará en una sola línea: .. toctree:: :maxdepth: 2 :glob:durante la transformación y dejarán de funcionar. En otras palabras, es imposible usar directivas de esta manera.
Wiktor Walc
@WiktorWalc No estoy muy familiarizado con Pandoc y realmente no lo he probado, pero tenía sentido, supongo. Oh bien. Lo intenté. ¿Supongo que puedes presentar un informe de error?
the_drow
@WiktorWalc: ..toctreeno es una sintaxis válida de Markdown. Usted escribe todo el documento en Markdown (y pierde las bondades de ReSt), o usa ReST. No puedes tener tu pastel y comértelo también.
Aditya
1
solo una pista: una solución sería usar filtros pandoc para omitir esas instrucciones especiales y dejarlas como están en la generación de salida. Sin embargo, no soy un mago de los filtros de Pandoc, y agrega complejidad adicional al esquema.
zmo
1

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/

jkmacc
fuente
Acabo de empezar a usar esto y es fantástico.
Rick apoya a Mónica el
0

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>
Donatello
fuente