🔧 MAINTAIN: Support include parser option in RST

[chrisjsewell]

supercedes #414

cc @cpitclaudel

closes #417
closes #388

[codecov]

Codecov Report

Merging #419 (6a87085) into master (61f1154) will increase coverage by 0.09%.
The diff coverage is 96.42%.

@@            Coverage Diff             @@
##           master     #419      +/-   ##
==========================================
+ Coverage   90.67%   90.77%   +0.09%     
==========================================
  Files          14       16       +2     
  Lines        1855     1875      +20     
==========================================
+ Hits         1682     1702      +20     
  Misses        173      173              

Flag	Coverage Δ
pytests	90.77% <96.42%> (+0.09%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

Impacted Files	Coverage Δ
myst_parser/sphinx_.py	0.00% <0.00%> (ø)
myst_parser/docutils_.py	100.00% <100.00%> (ø)
myst_parser/sphinx_parser.py	100.00% <100.00%> (+2.43%)	⬆️
myst_parser/sphinx_renderer.py	93.08% <100.00%> (ø)

---

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 61f1154...6a87085. Read the comment docs.

[chrisjsewell]

Note, this is not really the intended use case of myst_parser, so I won't be officially supporting it, i.e. if it does not work for whatever reasons, I won't treat that as a bug

[cpitclaudel]

Thanks!

Question about your last comment: is building with Sphinx the only supported use case, or is the plan to also support building with the standard Docutils pipeline? (or in fact with other programs that build on top of it, like Pelican?)

The reason I'm asking is that I use the standard Docutils pipeline in plenty of places, and I wouldn't be against migrating these documents to Markdown — but I want to make sure that things aren't going to break unexpectedly.

[choldgraf]

Cc @damianavila who was playing around with getting Myst to work in Nikola

[cpitclaudel]

I think we would be super nice to be able to use MyST with docutils — the way reCommonMark can be used and through the usual methods in docutils.core. This parser is a great step in this direction, and I've opened a related feature request at #420