Nienawidzę RST, ale kocham sfinksa. Czy istnieje sposób, w jaki sfinks czyta markdown zamiast reStructuredText?
python
markdown
python-sphinx
digi604
źródło
źródło
:param path:
itp.), Zobacz rozszerzenie Napoleon .Odpowiedzi:
„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:
Możesz oszukiwać i pisać „parser”, który używa Pandoc do konwersji markdown do RST i przekazania go do parsera RST :-).
Możesz użyć istniejącego parsera markdown-> XML i przekształcić wynik (używając XSLT?) Do schematu docutils.
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.
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 .
```eval_rst
ogrodzonym blokiem, a także skrótem dla dyrektywDIRECTIVE_NAME:: ...
.AKTUALIZACJA : MyST to kolejny czytnik docutins / Sphinx. Oparty na markdown-it-py, zgodny z CommonMark.
{ROLE_NAME}`...`
składnię ról.```{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ą:
`foo`{.method}
->`foo`:method:
.<span class="method">foo</span>
najdziwniejszego podejścia polegającego na wstawianiu wewnętrznych plików XML docutils!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 .źródło
myst-parser
do tej odpowiedzi. wygra.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 edytujconf.py
: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.
źródło
eval_rst
bloku ogrodzonego do wstawiania dowolnej konstrukcji / dyrektywy rST.ImportError: cannot import name 'DocParser'
na Sphinx 1.4.1 w Pythonie 3.4.3.pip install commonmark==0.5.5 --upgrade
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.
źródło
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:
dostosuj
conf.py
:źródło
cannot import name DocParser
, spróbujpip install commonmark==0.5.5
.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
toctree
bez powielania ich w przecenie.źródło
README.md
) w mojej bardziej wyczerpującej dokumentacji Sfinksa. Czy wiesz, czy to jest możliwe?Jest to teraz oficjalnie obsługiwane: http://www.sphinx-doc.org/en/stable/markdown.html
źródło
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.
źródło
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.
źródło
.. toctree:: :maxdepth: 2 :glob:
podczas transformacji i przestaną działać. Innymi słowy, niemożliwe jest stosowanie dyrektyw w ten sposób...toctree
niepoprawna 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.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/
źródło
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
źródło