Używanie sfinksa z Markdown zamiast RST

Nienawidzę RST, ale kocham sfinksa. Czy istnieje sposób, w jaki sfinks czyta markdown zamiast reStructuredText?

„Właściwym” sposobem na to byłoby napisanie parsera docutils dla markdown. (Plus opcja Sphinx do wybrania parsera). Piękno tego byłoby natychmiastowe wsparcie dla wszystkich formatów wyjściowych docutils (ale możesz się tym nie przejmować, ponieważ większość narzędzi już istnieje). Sposoby podejścia do tego bez rozwijania analizatora składni od zera:

1. Możesz oszukiwać i pisać „parser”, który używa Pandoc do konwersji markdown do RST i przekazania go do parsera RST :-).

2. Możesz użyć istniejącego parsera markdown-> XML i przekształcić wynik (używając XSLT?) Do schematu docutils.

3. Możesz wziąć istniejący parser języka pytdown, który pozwala zdefiniować niestandardowy moduł renderujący i zmusić go do zbudowania drzewa węzłów docutils.

4. Możesz rozwidlić istniejący czytnik RST, wyrywając wszystko, co nie ma znaczenia dla markdown i zmieniając różne składnie ( to porównanie może pomóc) ...
   EDYCJA: Nie polecam tej trasy, chyba że jesteś przygotowany do jej dokładnego przetestowania. Markdown ma już zbyt wiele subtelnie różnych dialektów, co prawdopodobnie spowoduje jeszcze jeden ...

AKTUALIZACJA: https://github.com/sgenoud/remarkdown to czytnik przecen dla docutils. Nie wymagał żadnego z powyższych skrótów, ale używa gramatyki PEG Parsley inspirowanej peg-markdown .

• Nie obsługuje jeszcze dyrektyw.

AKTUALIZACJA: https://github.com/readthedocs/recommonmark i jest kolejnym czytnikiem docutils, natywnie obsługiwanym przez ReadTheDocs. Pochodzi z remarkdown, ale używa parsera CommonMark-py .

• To może konwertować konkretne bardziej lub mniej naturalnych składni Markdown do listy odpowiednich struktur np linków do toctree. * Nie ma ogólnej natywnej składni ról.
• Obsługuje osadzanie dowolnej zawartości rST, w tym dyrektyw, z ```eval_rstogrodzonym blokiem, a także skrótem dla dyrektyw DIRECTIVE_NAME:: ....

AKTUALIZACJA : MyST to kolejny czytnik docutins / Sphinx. Oparty na markdown-it-py, zgodny z CommonMark.

• Ma ogólną {ROLE_NAME}`...`składnię ról.
• Ma ogólną składnię dla dyrektyw z ```{DIRECTIVE_NAME} ...blokami ogrodzonymi.

We wszystkich przypadkach musisz wymyślić rozszerzenia Markdown, aby reprezentowały dyrektywy i role Sfinksa . Chociaż możesz nie potrzebować ich wszystkich, niektóre z nich .. toctree::są niezbędne.
Myślę, że to najtrudniejsza część. reStructuredText przed rozszerzeniami Sfinksa był już bogatszy niż obniżka. Nawet mocno rozszerzone przeceny, takie jak pandoc , są najczęściej podzbiorem zestawu funkcji rST. To dużo ziemi do pokonania!

Jeśli chodzi o implementację, najłatwiej jest dodać ogólny konstrukt wyrażający dowolną rolę / dyrektywę docutils. Oczywistymi kandydatami do inspiracji składni są:

• Składnia atrybutu, na którą pandoc i niektóre inne implementacje pozwalają już w wielu konstrukcjach wbudowanych i blokowych. Na przykład `foo`{.method}-> `foo`:method:.
• HTML / XML. Od <span class="method">foo</span>najdziwniejszego podejścia polegającego na wstawianiu wewnętrznych plików XML docutils!
• Jakiś YAML dla dyrektyw?

Ale takie ogólne mapowanie nie będzie najbardziej markowym rozwiązaniem ... Obecnie najbardziej aktywnymi miejscami do dyskusji na temat rozszerzeń przecen są https://groups.google.com/forum/#!topic/pandoc-discuss , https: // github.com/scholmd/scholmd/

Oznacza to również, że nie możesz po prostu ponownie użyć parsera przecenienia bez jego rozszerzenia. Pandoc ponownie zasługuje na swoją reputację jako szwajcarski scyzoryk do konwersji dokumentów dzięki obsłudze niestandardowych plików . (W rzeczywistości, gdybym do tego podszedł, spróbowałbym zbudować ogólny most między czytnikami / transformatorami / pisarzami docutils a czytnikami / filtrami / pisarzami pandoc. To więcej niż potrzebujesz, ale wypłata byłaby znacznie szersza niż tylko sfinks / obniżka cen.)

Szalony alternatywny pomysł: zamiast rozszerzać Markdown do obsługi Sfinksa, rozszerz reStructuredText, aby obsługiwać (głównie) superset Markdown! Piękno polega na tym, że będziesz mógł korzystać z dowolnych funkcji Sfinksa takimi, jakie są, ale będziesz w stanie pisać większość treści w przecenach.

Już jest nakłada się znaczna liczba składni ; przede wszystkim składnia linków jest niezgodna. Myślę, że jeśli dodasz obsługę RST dla linków do znaczników i ###-stylery stylów, i zmienisz domyślną `backticks`rolę na literalną, a może zmienisz wcięte bloki na literalne (obecnie RST obsługuje > ...cytaty), dostaniesz coś użytecznego, co obsługuje większość markdown .

Możesz użyć Markdown i reStructuredText w tym samym projekcie Sphinx. Jak to zrobić, jest zwięźle udokumentowane w książce Read The Docs .

Zainstaluj Polecenie polecania ( pip install recommonmark), a następnie edytuj conf.py:

from recommonmark.parser import CommonMarkParser

source_parsers = {
    '.md': CommonMarkParser,
}

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

Stworzyłem mały przykładowy projekt na Githubie (serra / sphinx-with-markdown) pokazujący, jak to działa (i to). Wykorzystuje CommonMark 0.5.4 i ponownie zaleca 0.4.0.

To nie używa Sphinx, ale MkDocs zbuduje twoją dokumentację za pomocą Markdown. Nienawidzę również pierwszego i do tej pory naprawdę podobało mi się MkDocs.

Aktualizacja: jest to teraz oficjalnie obsługiwane i dokumentowane w dokumentach sfinksa .

Wygląda na to, że podstawowa implementacja dotarła do Sfinksa, ale słowo jeszcze się nie pojawiło. Zobacz komentarz do wydania github

zainstalować zależności:

pip install commonmark recommonmark

dostosuj conf.py:

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

Markdown i ReST robią różne rzeczy.

RST zapewnia model obiektowy do pracy z dokumentami.

Markdown umożliwia grawerowanie fragmentów tekstu.

Wydaje się rozsądne, aby chcieć odwoływać się do fragmentów treści Markdown z projektu sfinksa, używając RST do usunięcia ogólnej architektury informacji i przepływu większego dokumentu. Niech markdown robi to, co robi, co pozwala pisarzom skupić się na pisaniu tekstu.

Czy istnieje sposób odwoływania się do domeny przecenionej, aby wygrawerować treść taką, jaka jest? Wygląda na to, że RST / sfinks zadbał o takie funkcje, jak toctreebez powielania ich w przecenie.

Jest to teraz oficjalnie obsługiwane: http://www.sphinx-doc.org/en/stable/markdown.html

Poszedłem z sugestią Beni, aby użyć pandoc do tego zadania. Po zainstalowaniu poniższy skrypt przekonwertuje wszystkie pliki Markdown w katalogu źródłowym na pliki rst, abyś mógł po prostu napisać całą dokumentację w Markdown. Mam nadzieję, że jest to przydatne dla innych.

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

Istnieje obejście.
Skrypt sphinx-quickstart.py generuje plik Makefile.
Możesz łatwo wywołać Pandoc z Makefile za każdym razem, gdy chcesz wygenerować dokumentację w celu konwersji Markdown na reStructuredText.

Oto nowa opcja. MyST dodaje pewne funkcje do Markdown, które pozwalają Sphinxowi budować dokumenty tak jak rst. https://myst-parser.readthedocs.io/en/latest/

Zauważ, że dokumentacja budynku z wykorzystaniem maven i osadzonej obsługi Sphinx + MarkDown jest w pełni obsługiwana przez następującą wtyczkę 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>