One of my annoying itch is documentation.<\/p>\n
I like a lot sphinx<\/a> as toolchain but the underlying rst<\/a> has a quite steep learning curve and it is outright ugly to write in many common situation.<\/p>\n I like a lot kramdown<\/a> as syntax but sadly it is ruby-only and overall the Markdown implementation for python usually have a good number of shortcomings, including the quite annoying part of not having a full AST for the extensions, making quite a pain to proper translations (e.g. moin-2 markdown can’t use the extension supported by the original since they get mangled badly during the process of node matching)…<\/p>\n CommonMark<\/a> is a cooperative effort to build actually a proper specification of the ubiquitous markdown syntax. The implementations usually provide a full AST and the python one (derived from the javascript one) is quite easy to understand, fast enough and easy to extend.<\/p>\n I know that somebody else already tried to bridge<\/a> docutils and markdown, sadly ReStructuredText is much richer than CommonMark core, at least I should complete my work to support attributes<\/a> so the manpage output would work mostly as intended.<\/p>\n The directive<\/a> system is quite different from the one currently discussed<\/a> and that will cause a good deal of headache to map the sphinx extension to document the function parameters.<\/p>\n As usual help welcome!<\/p>\n","protected":false},"excerpt":{"rendered":" One of my annoying itch is documentation. I like a lot sphinx as toolchain but the underlying rst has a quite steep learning curve and it is outright ugly to write in many common situation. I like a lot kramdown as syntax but sadly it is ruby-only and overall the Markdown implementation for python usually … Continue reading Bridging Markdown to sphinx<\/span><\/a><\/p>\n","protected":false},"author":10,"featured_media":0,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"spay_email":"","jetpack_publicize_message":"","jetpack_is_tweetstorm":false,"jetpack_publicize_feature_enabled":true},"categories":[1],"tags":[],"jetpack_publicize_connections":[],"jetpack_featured_media_url":"","jetpack_sharing_enabled":true,"jetpack_shortlink":"https:\/\/wp.me\/p1aGWH-6s","_links":{"self":[{"href":"https:\/\/blogs.gentoo.org\/lu_zero\/wp-json\/wp\/v2\/posts\/400"}],"collection":[{"href":"https:\/\/blogs.gentoo.org\/lu_zero\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/blogs.gentoo.org\/lu_zero\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/blogs.gentoo.org\/lu_zero\/wp-json\/wp\/v2\/users\/10"}],"replies":[{"embeddable":true,"href":"https:\/\/blogs.gentoo.org\/lu_zero\/wp-json\/wp\/v2\/comments?post=400"}],"version-history":[{"count":2,"href":"https:\/\/blogs.gentoo.org\/lu_zero\/wp-json\/wp\/v2\/posts\/400\/revisions"}],"predecessor-version":[{"id":451,"href":"https:\/\/blogs.gentoo.org\/lu_zero\/wp-json\/wp\/v2\/posts\/400\/revisions\/451"}],"wp:attachment":[{"href":"https:\/\/blogs.gentoo.org\/lu_zero\/wp-json\/wp\/v2\/media?parent=400"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/blogs.gentoo.org\/lu_zero\/wp-json\/wp\/v2\/categories?post=400"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/blogs.gentoo.org\/lu_zero\/wp-json\/wp\/v2\/tags?post=400"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}Enters CommonMark<\/h2>\n
parsley<\/code> is a tad slow for the purpose. I gutted away the original markdown parser and wired in commonmark-py<\/a> the result is a decently fast implementation that maps most of the core syntax to the docutils AST and thus makes possible to write in markdown and get it converted using the docutils output formats.<\/p>\nWhat’s left<\/h2>\n