Używanie sfinksa z Markdown zamiast RST

212

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

digi604
źródło
1
Nie znam żadnej dostępnej opcji. Ale zauważ, że RST ma znacznie więcej opcji niż obniżka pod względem rozszerzalności. W zależności od projektu może to nie być wystarczające.
Wolph
2
Istnieje podzbiór rST, który jest w większości poprawnym znacznikiem. Jeśli nie znosisz list pól Sfinksa ( :param path:itp.), Zobacz rozszerzenie Napoleon .
Beni Cherniavsky-Paskin
3
Jeśli chcesz udokumentować swój projekt Python w Markdown za pomocą Sphinx, głosuj na prośbę o funkcję na bitbucket.org/birkenfeld/sphinx/issue/825/...
Pułkownik Panika
1
Patrząc na ten komentarz, wydaje się, że można połączyć dwa: read-the-docs.readthedocs.org/en/latest/…
Stefan van der Walt
2
Podstawowa obsługa Markdown wreszcie
dotarła

Odpowiedzi:

97

„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 .

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 .

Beni Cherniavsky-Paskin
źródło
17
Wnioskuję z braku postępów w tej dziedzinie, ReST może być po prostu wystarczająco dobry i niewystarczająco odmienny, aby Markdown był wart tego przedsięwzięcia.
Prof. Falken
5
TLDR: Użyj polecenia reconmark, aby napisać dokumentację Sphinx za pomocą Markdown.
ostrokach
zasugeruj dodanie nowego myst-parserdo tej odpowiedzi. wygra.
Rick wspiera Monikę
92

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.

Marijn
źródło
4
Beni wspomina o tym podejściu w swojej bardzo wyczerpującej odpowiedzi powyżej . Uważam jednak, że to pytanie zasługuje na tę prostą odpowiedź.
Marijn,
2
Ważne jest, aby przeczytać Polecenie polecone.readthedocs.org/en/latest/auto_structify.html , szczególnie jak stworzyć toctree i jak używać eval_rstbloku ogrodzonego do wstawiania dowolnej konstrukcji / dyrektywy rST.
Beni Cherniavsky-Paskin
wymagało to zainstalowania polecenia reconmark i
commonmark
1
Dostaję się ImportError: cannot import name 'DocParser'na Sphinx 1.4.1 w Pythonie 3.4.3.
detly
2
@detly: The ImportError wynika z najnowszej wersji (0.6.0) commonmark zerwania kompatybilności z recommonmark: patrz github.com/rtfd/recommonmark/issues/24 . Rozwiązanie:pip install commonmark==0.5.5 --upgrade
Kadee
30

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.

jkmacc
źródło
5
MkDocs również tutaj działały bardzo dobrze, w przypadku dokumentacji użytkownika końcowego. Wciąż szukam użycia przeceny w dokumentach ...
Marcus Ottosson
2
Tak bardzo za to.
jkmacc
1
Hej, dzięki - MkDocs jest niesamowity! Tracę dużo mocy i funkcji w porównaniu do Sfinksa i RST, to na pewno… ale jest niesamowicie nieskomplikowane, usprawnione i tak łatwe i szybkie w użyciu. Idealny do prawie wszystkich moich przypadków użycia - takich jak krótkie instrukcje instalacji i krótki samouczek z kilkoma przykładami. W kilku przypadkach, w których potrzebuję dużo kodu źródłowego wyjaśniającego - dokumentacji klasy Ig i wywołania funkcji - trzymam się Sphinxa.
Brutus,
W chwili pisania tego tekstu obsługuje jednak tylko 2 poziomy wcięcia spisu treści.
wrygiel
@wrygiel Nie masz racji - liczba renderowanych poziomów spisu treści zależy od używanego motywu.
Ale
27

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']
Oliver Bestwalter
źródło
1
Jeśli tak cannot import name DocParser, spróbuj pip install commonmark==0.5.5.
Roger Dahl,
1
Link do dokumentów sfinksa powinien być sphinx-doc.org/en/master/usage/markdown.html
Paul Brannan
21

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.

bewest
źródło
5
„Wydaje się rozsądne, aby chcieć odwoływać się do twoich fragmentów treści Markdown z twojego projektu sfinksa” - tak naprawdę chcę to zrobić; Chcę zawrzeć trochę treści (mojej README.md) w mojej bardziej wyczerpującej dokumentacji Sfinksa. Czy wiesz, czy to jest możliwe?
detly
8

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(' '))
igniteflow
źródło
1

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.

the_drow
źródło
3
O ile nie zrobię czegoś złego, zastąpienie ReST Markdownem nie jest takie proste. Jeśli użyjesz instrukcji takich jak toctree w pliku źródłowym Markdown, Pandoc zmieni je w jedną linię: .. toctree:: :maxdepth: 2 :glob:podczas transformacji i przestaną działać. Innymi słowy, niemożliwe jest stosowanie dyrektyw w ten sposób.
Wiktor Walc,
@WiktorWalc Nie jestem zbyt obeznany z pandocem i tak naprawdę go nie próbowałem, ale chyba miał sens. No cóż. Próbowałem. Myślę, że możesz zgłosić błąd?
the_drow
@WiktorWalc: ..toctreeniepoprawna składnia Markdown. Albo piszesz cały dokument w Markdown (i tracisz subtelności ReSt), albo używasz ReST. Nie możesz mieć ciasta i jesz.
Aditya
1
tylko wskazówka: rozwiązaniem byłoby użycie filtrów pandoc, aby pominąć te specjalne instrukcje i pozostawić je bez zmian w generowaniu danych wyjściowych. Jednak nie jestem czarodziejem filtrów pandoc, co dodatkowo komplikuje schemat.
zmo
0

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>
Donatello
źródło