python - software - sphinx read the docs

Usar sphinx con Markdown en lugar de RST

Question

Odio RST pero amo la esfinge. ¿Hay alguna manera de que sphinx lea markdown en lugar de reStructuredText?

Answer 1

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

Answer 2

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

Answer 3

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

Answer 4

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

Answer 5

La forma "correcta" de hacer eso 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 la compatibilidad instantánea para todos los formatos de salida de docutils (pero puede que no te importe eso, ya que para la mayoría ya existen herramientas de rebajas similares). Formas de abordar eso sin desarrollar un analizador desde cero:

• Puede copiar y escribir un "analizador sintáctico" que usa Pandoc para convertir el descuento en RST y pasarlo al analizador RST :-).

• Puede utilizar un analizador existente markdown-> XML y transformar el resultado (utilizando XSLT?) En el esquema de docutils.

• Podría tomar algún analizador sintáctico de reducción de python existente que le permita definir un renderizador personalizado y hacerlo construir 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 en gran medida. Markdown ya tiene demasiados dialectos sutilmente diferentes y esto probablemente resultará en yet-another-one ...

ACTUALIZACIÓN: https://github.com/sgenoud/remarkdown es un lector de descuento para docutils. No tomó ninguno de los métodos abreviados anteriores, pero usa una gramática Parsley PEG inspirada en el peg-markdown . Aún no es compatible con las directivas.

ACTUALIZACIÓN: https://github.com/rtfd/recommonmark y es otro lector docutils, nativamente compatible con ReadTheDocs. Derivado de un comentario, pero usa el analizador CommonMark-py . No admite directivas, pero puede convertir sintaxis de Markdown más o menos naturales en estructuras apropiadas, por ejemplo, lista de enlaces a un árbol. Para otras necesidades, un bloque ```eval_rst cercado le permite incrustar cualquier directiva rST.

En todos los casos, deberá inventar extensiones de Markdown para representar las directivas y los 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 el descuento. Incluso el pandoc''s muy extendido, como el de pandoc''s , es principalmente un subconjunto del conjunto de características rST. ¡Eso es mucho terreno para cubrir!

En lo que respecta a la implementación, lo más fácil es agregar un constructo genérico para expresar cualquier rol / directiva de docutils. Los candidatos obvios para la inspiración de la 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> al enfoque kludgiest de solo insertar docutils XML interno!
• ¿Algún tipo de YAML para directivas?

Pero un mapeo genérico de este tipo no será la solución de mayor reducción ... Actualmente, los lugares más activos para analizar las extensiones de rebajas 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 rebajas sin ampliarlo de alguna manera. Pandoc vuelve a estar a la altura de su reputación como la navaja suiza de la conversión de documentos mediante el soporte de filtros personalizados . (De hecho, si tuviera que abordar esto, trataría de construir un puente genérico entre docutils readers / transformers / writers y pandoc readers / filters / writers. 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, extiende reStructuredText para apoyar (principalmente) un superconjunto de rebajas. Lo mejor es que podrá usar cualquier característica de Sphinx tal como está y, sin embargo, podrá escribir la mayoría del contenido en el descuento.

Ya existe una considerable superposición de sintaxis ; más notablemente, la sintaxis del enlace es incompatible. Creo que si agregas soporte a RST para los enlaces de rebajas, y ### style headers, y cambias el rol predeterminado de `backticks` a literal, y quizás cambies los bloques con sangría para que signifique literal (RST soporta > ... para citas ahora), obtendrá algo utilizable que admita la mayoría del descuento.

Answer 6

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 sus bits de contenido de Markdown de su proyecto de esfinge, utilizando RST para anular la arquitectura de información general y el flujo de un documento más grande. Deje que el descuento haga lo que hace, lo que permite a los escritores centrarse en escribir texto.

¿Hay alguna manera de hacer referencia a un dominio de rebajas, solo para grabar el contenido tal como está? RST / sphinx parece haberse ocupado de funciones como toctree sin duplicarlas en el marcado.

Answer 7

Puede usar Markdown y reStructuredText en el mismo proyecto de Sphinx. Cómo hacer esto se documenta sucintamente 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 funciona (y eso). Utiliza CommonMark 0.5.4 y recommonmark 0.4.0.

Answer 8

Tenga en cuenta que la creación de documentación con Maven y el soporte incrustado 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>

Answer 9

Actualización: esto ahora es oficialmente compatible y documentado en los documentos de esfinge .

Parece que una implementación básica ha llegado a Sphinx, pero todavía no se ha corrido la voz. Ver el comentario del problema de Github

instalar dependencias:

pip install commonmark recommonmark

ajustar conf.py :

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