Sfenks'i RST yerine Markdown ile kullanma

RST'den nefret ediyorum ama sfenks seviyorum. Sfenks'in reStructuredText yerine markdown okumasının bir yolu var mı?

Bunu yapmak için "uygun" yolu, markdown için bir docutils ayrıştırıcı yazmak olacaktır . (Ayrıca ayrıştırıcıyı seçmek için bir Sphinx seçeneği.) Bunun güzelliği, tüm docutils çıktı formatları için anında destek olacaktır (ancak çoğu için benzer işaretleme araçları zaten mevcut olduğu için bunu umursamayabilirsiniz). Sıfırdan bir ayrıştırıcı geliştirmeden buna yaklaşmanın yolları:

1. Hile ve Markoc RST dönüştürmek ve bunu RST ayrıştırıcı geçmek için Pandoc kullanan bir "ayrıştırıcı" yazabilirsiniz :-).

2. Mevcut bir markdown-> XML ayrıştırıcısını kullanabilir ve sonucu (XSLT? Kullanarak) docutils şemasına dönüştürebilirsiniz.

3. Özel bir oluşturucu tanımlamanıza ve docutils düğüm ağacını oluşturmasına izin veren mevcut bazı python işaretleme ayrıştırıcısını alabilirsiniz .

4. Mevcut RST okuyucuyu çatallandırabilir, işaretleme ile ilgili olmayan her şeyi çıkarabilir ve farklı sözdizimlerini değiştirebilirsiniz ( bu karşılaştırma kudreti yardım) ...
   EDIT: Eğer ağır test etmek hazırlanan sürece ben bu yolu tavsiye etmiyoruz. Markdown zaten çok fazla ince farklı lehçeye sahip ve bu muhtemelen başka bir tane ile sonuçlanacak ...

GÜNCELLEME: https://github.com/sgenoud/remarkdown docutils için bir etiketleme okuyucusudur. Yukarıdaki kısayolların hiçbirini almadı, ancak bir peg-markdown'dan esinlenen Maydanoz PEG dilbilgisi .

• Henüz yönergeleri desteklemiyor.

GÜNCELLEME: https://github.com/readthedocs/recommonmark ve ReadTheDocs'da yerel olarak desteklenen başka bir docutils okuyucusudur. Yeniden değerlendirmeden türetilmiş ancak CommonMark-py ayrıştırıcısını kullanmaktadır.

• Bu dönüştürebilirsiniz bir toctree bağlantıların uygun yapıların örneğin listeye özgü daha çok veya daha az doğal Markdown sözdizimi. * Roller için genel yerel sözdizimi yoktur.
• Direktifler de dahil olmak üzere herhangi bir rST içeriğinin ```eval_rstçitle çevrili bir blokla ve direktifler için bir kısayolla gömülmesini destekler DIRECTIVE_NAME:: ....

GÜNCELLEME : MyST başka bir docutins / Sfenks okuyucusudur. Markdown-it-py tabanlı, CommonMark uyumlu.

• {ROLE_NAME}`...`Roller için genel bir sözdizimine sahiptir .
• ```{DIRECTIVE_NAME} ...Çitlerle çevrili bloklara sahip direktifler için genel bir sözdizimine sahiptir .

Gelen tüm durumlarda, temsil etmeye Markdown uzantıları icat etmek gerekir Sfenks direktifleri ve rolleri . Bunların hepsine ihtiyacınız olmayabilir, ancak bazıları .. toctree::önemlidir.
Bu bence en zor kısım. Sphinx uzantılarından önceki reStructuredText, zaten işaretlemeden daha zengindi. Çok genişletilmiş etiketleme bile, örneğinPandos çoğunlukla rST özellik kümesinin bir alt kümesidir. Örtmek için çok yer var!

Uygulama açısından, en kolay şey, herhangi bir docutils rolünü / yönergesini ifade etmek için genel bir yapı eklemektir. Sözdizimi ilhamı için açık adaylar:

• Pandoc ve diğer bazı uygulamaların birçok satır içi ve blok yapısında zaten izin verdiği özellik sözdizimi. Örneğin`foo`{.method} -> `foo`:method:.
• HTML / XML. itibaren<span class="method">foo</span> sadece docutils iç XML ekleme kludgiest yaklaşıma!
• Direktifler için bir çeşit YAML?

Ancak böyle bir jenerik haritalama en markdown-ish çözümü olmayacaktır ... Şu anda markdown uzantılarını tartışmak için en aktif yerler https://groups.google.com/forum/#!topic/pandoc-discuss , https: // github.com/scholmd/scholmd/

Bu, bir etiketleme ayrıştırıcısını bir şekilde genişletmeden tekrar kullanamayacağınız anlamına gelir. Pandoc, özel filtes'i destekleyerek belge dönüştürme işleminin İsviçre çakısı olarak ününü tekrar karşılıyor . (Aslında buna yaklaşacak olsaydım, docutils okuyucular / transformatörler / yazarlar ve pandoc okuyucular / filtreler / yazarlar arasında genel bir köprü kurmaya çalışırdım. İhtiyaçtan daha fazla ama getirisi sadece sfenks / markdown.)

Alternatif çılgın fikir: Sfenks'i işlemek için işaretlemeyi uzatmak yerine, reStructuredText'i (çoğunlukla) bir etiketleme üst kümesini desteklemek için genişletin! Güzellik, herhangi bir Sphinx özelliğini olduğu gibi kullanabilmenize rağmen, çoğu içeriği markdown'da yazabilmenizdir.

Zaten hatırı sayılır bir sözdizimi çakışması var ; en önemlisi bağlantı sözdizimi uyumsuzdur. İşaretleme bağlantıları ve ###stil üstbilgileri için RST'ye destek ekler ve varsayılan `backticks`rolü değişmez olarak değiştirirseniz ve belki girintili blokları değişmez anlamına gelir (günümüzde > ...alıntılar için RST destekler ), çoğu markdown'u destekleyen kullanılabilir bir şey alırsınız. .

Markdown ve reStructuredText öğelerini aynı Sphinx projesinde kullanabilirsiniz. Bunun nasıl yapılacağı tamamen belgelenmiştir Oku .

Recommonmark ( pip install recommonmark) 'ı yükleyin ve düzenleyin conf.py:

from recommonmark.parser import CommonMarkParser

source_parsers = {
    '.md': CommonMarkParser,
}

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

Github'da (serra / sfenks-markdown) nasıl (ve bunun) çalıştığını gösteren küçük bir örnek proje oluşturdum . CommonMark 0.5.4 ve öneri 0.4.0 kullanır.

Bu Sphinx kullanmaz, ancak MkDocs belgelerinizi Markdown kullanarak oluşturacaktır. Ayrıca rst nefret ve şimdiye kadar gerçekten MkDocs keyif aldık.

Güncelleme: Bu artık sfenks belgelerinde resmi olarak destekleniyor ve belgeleniyor .

Temel bir uygulama Sfenks'e girmiş gibi görünüyor, ancak kelime henüz tamamlanmadı. Github sorunu yorumuna bakın

yükleme bağımlılıkları:

pip install commonmark recommonmark

ayarlamak conf.py:

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

Markdown ve ReST farklı şeyler yapar.

RST, belgelerle çalışmak için bir nesne modeli sağlar.

Markdown, metin parçalarını kazımak için bir yol sağlar.

Daha büyük bir belgenin genel bilgi mimarisini ve akışını saptamak için RST'yi kullanarak, Sfenks projenizden Markdown içeriği parçalarına başvurmak makul görünüyor. İşaretlemenin yaptıklarını yapmasına izin verin, bu da yazarların metin yazmaya odaklanmasına izin verir.

Yalnızca bir içeriği olduğu gibi kazımak için bir işaretleme alanına başvurmanın bir yolu var mı? RST / sfenks toctree, markdown'da çoğaltmadan gibi özelliklere sahip gibi görünüyor .

Bu artık resmi olarak desteklenmektedir: http://www.sphinx-doc.org/en/stable/markdown.html

Beni'nin bu görev için pandoc kullanma önerisiyle gittim. Kurulduktan sonra aşağıdaki komut dosyası, kaynak dizindeki tüm markdown dosyalarını rst dosyalarına dönüştürür, böylece tüm belgelerinizi markdown'a yazabilirsiniz. Umarım bu diğerleri için yararlıdır.

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

Bir çözüm var.
Sphinx-quickstart.py betiği Makefile oluşturur.
Markdown'u reStructuredText'e dönüştürmek için belgeleri her oluşturmak istediğinizde Pandoc'u Makefile'den kolayca çağırabilirsiniz.

İşte yeni bir seçenek. MyST, Markdown'a Sphinx'in rst gibi dokümanlar oluşturmasına izin veren bazı özellikler ekler. https://myst-parser.readthedocs.io/en/latest/

Maaven kullanarak belge oluşturma ve gömülü Sphinx + MarkDown desteğini aşağıdaki maven eklentisi tarafından tamamen desteklendiğini unutmayın:

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>