Odio RST pero amo a la esfinge. ¿Hay alguna forma en que la esfinge lea Markdown en lugar de reStructuredText?
:param path:
etc.), vea la extensión de Napoleón .
Odio RST pero amo a la esfinge. ¿Hay alguna forma en que la esfinge lea Markdown en lugar de reStructuredText?
:param path:
etc.), vea la extensión de Napoleón .
Respuestas:
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:
Podrías hacer trampa y escribir un "analizador" que usa Pandoc para convertir Markdown a RST y pasarlo al analizador RST :-).
Puede usar un analizador Markdown-> XML existente y transformar el resultado (¿usando XSLT?) En el esquema docutils.
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.
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 .
```eval_rst
bloque 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.
{ROLE_NAME}`...`
sintaxis genérica para roles. ```{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:
`foo`{.method}
-> `foo`:method:
.<span class="method">foo</span>
el enfoque más difícil de insertar simplemente docutils XML interno!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 .
myst-parser
a esta respuesta. va a ganar
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.
eval_rst
bloque vallado para insertar cualquier construcción / directiva rST.
ImportError: cannot import name 'DocParser'
en Sphinx 1.4.1 bajo Python 3.4.3.
pip install commonmark==0.5.5 --upgrade
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']
cannot import name DocParser
, inténtalo pip install commonmark==0.5.5
.
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 toctree
sin duplicarlas en el descuento.
README.md
) en mi documentación más completa de Sphinx. ¿Sabes si esto es posible?
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.
.. toctree:: :maxdepth: 2 :glob:
durante la transformación y dejarán de funcionar. En otras palabras, es imposible usar directivas de esta manera.
..toctree
no 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.
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>