search

executablebooks / markdown-it-docutils

A markdown-it plugin for implementing docutils style roles/directives.
https://executablebooks.github.io/markdown-it-docutils/
MIT License
12 stars 8 forks source link

Directives to add #7

Open chrisjsewell opened 3 years ago

chrisjsewell commented 3 years ago

Some that I definitely want in there:

From "core":

Maybe also things from extensions (optional?):

chrisjsewell commented 2 years ago

Here's a list from https://rst-to-myst.readthedocs.io/en/latest/cli.html of all the "base" docutils+sphinx roles/directives:

From rst2myst roles list:

abbr abbreviation acronym anonymous-reference any citation-reference code command dfn download emphasis eq file footnote-reference guilabel index kbd literal mailheader makevar manpage math menuselection mimetype named-reference newsgroup pep pep-reference program raw regexp restructuredtext-unimplemented-role rfc rfc-reference samp strong subscript substitution-reference superscript target title-reference uri-reference c:data c:enum c:enumerator c:expr c:func c:macro c:member c:struct c:texpr c:type c:union c:var cpp:any cpp:class cpp:concept cpp:enum cpp:enumerator cpp:expr cpp:func cpp:member cpp:struct cpp:texpr cpp:type cpp:union cpp:var js:attr js:class js:data js:func js:meth js:mod math:numref py:attr py:class py:const py:data py:exc py:func py:meth py:mod py:obj rst:dir rst:role std:doc std:envvar std:keyword std:numref std:option std:ref std:term std:token

From rst2myst directives list:

acks admonition attention caution centered class code code-block codeauthor compound container contents cssclass csv-table danger date default-domain default-role deprecated describe epigraph error figure footer header highlight highlights hint hlist image important include index line-block list-table literalinclude math meta moduleauthor note object only parsed-literal pull-quote raw replace restructuredtext-test-directive role rst-class rubric sectionauthor sectnum seealso sidebar sourcecode table tabularcolumns target-notes tip title toctree topic unicode versionadded versionchanged warning c:alias c:enum c:enumerator c:function c:macro c:member c:namespace c:namespace-pop c:namespace-push c:struct c:type c:union c:var cpp:alias cpp:class cpp:concept cpp:enum cpp:enum-class cpp:enum-struct cpp:enumerator cpp:function cpp:member cpp:namespace cpp:namespace-pop cpp:namespace-push cpp:struct cpp:type cpp:union cpp:var js:attribute js:class js:data js:function js:method js:module py:attribute py:class py:classmethod py:currentmodule py:data py:decorator py:decoratormethod py:exception py:function py:method py:module py:property py:staticmethod rst:directive rst:directive:option rst:role std:cmdoption std:envvar std:glossary std:option std:productionlist std:program
rowanc1 commented 2 years ago

Goal - get these into a spreadsheet/doc to help prioritize them and exclude various roles/directives.

mgielda commented 2 years ago

+1 for sphinx-tabs and sphinx-inline-tabs!

These are super useful for all sorts of documentation, and are so frustrating to write in the regular, nested rst syntax. MyST makes it so much easier, and in-browser rendering thereof would be perfect.

Thanks for this effort. BTW am I right in understanding markdown-it-docutics supersedes markdown-it-myst?

chrisjsewell commented 2 years ago

+1 for sphinx-tabs and sphinx-inline-tabs!

well https://sphinx-design.readthedocs.io/en/furo-theme/tabs.html are the way forward 😉

Thanks for this effort. BTW am I right in understanding markdown-it-docutics supersedes markdown-it-myst?

So the idea is that eventually markdown-it-myst will be updated, to combine this plugin with others required by myst (https://github.com/executablebooks/markdown-it-dollarmath, etc) into a single "myst parser"

For example, I am currently doing this directly in https://github.com/executablebooks/myst-vs-code/blob/c8c96542171ebe6ccdd896cf8337a5ffffeb73d4/src/extension.ts#L1

mgielda commented 2 years ago

Ah! I see. Sphinx-design is the new Sphinx-panels. Fancy, but I do like the gracefuleness of the inline tabs (most of the time the top-level "tab-set" directive is indeed redundant, so having an option to just have a bunch of neighboring tabs be grouped by default is pretty smart). Also small interoperable plugins sound like a nice idea, a bit worried about pulling in a lot of things of which you will still mostly use tabs ;)

Having said that - hey, if you implement sphinx-design, that's what I'm gonna use :) this is not a big deal.

Thanks for the explanation of your plans re myst parsing. I think the docutils part is really important as it is the main point of interop with Sphinx etc.

chrisjsewell commented 2 years ago

The evolution of tabs was actually; (1) I didn't really like the implementation/look of the ones in sphinx-tabs, so added tabs to sphinx-panels, (2) pradyunsg didn't like the fact that in sphinx-panels you have to load the full css framework and no syncronised tabs, so copied the logic from sphinx-panels to sphinx-inline-tabs, (3) In sphinx-design I removed the dependency on bootstrap and added the tab synchronisation, so pradsyung is back on board (https://github.com/executablebooks/sphinx-design/pull/22) lol

chrisjsewell commented 2 years ago

Thanks for the explanation of your plans re myst parsing. I think the docutils part is really important as it is the main point of interop with Sphinx etc.

yeh its just trying to get the balance, between trying to get myst as something that is not dependent on docutils/sphinx (and thus python), but not ending up re-writing the whole of these packages, see: #18

agoose77 commented 2 years ago

I'd like to propose that we add the figure-md directive for figures whose contents are written in Markdown?