Build single pages with docutils (instead of Sphinx) #420
Comments
choldgraf
changed the title
|
I updated the title to be a bit more general, since I think what you really want is to be able to build with docutils directly, instead of going to Sphinx via docutils. Is that right? (if so, configuration with Also - I'm curious why it wouldn't be acceptable to just use Sphinx but with a theme that was suited for single pages. What are the major downsides there for you? |
Yep, precisely. But I think you're too pessimistic :) The code in this repo is 95% of the way there — docutils.conf is really the last missing step (I know that because in Alectryon you can already convert markdown to html using MyST + docutils, and the only part that's not working is docutils.conf (modulo the bugs like #418, which is easily fixed, and #406, which is quite painful).
The overhead of conf.py: I use Sphinx heavily for larger projects, but for single pages it's not convenient at the moment: it doesn't have a good command line interface to mirror conf.py, so you need to write a new conf.py for each document. And docutils |
|
Also, of course, there's the hope that we could have MyST as part of the standard docutils pipeline at some point, as was discussed in #347 |
|
Yep, very quickly, I certainly think it is feasible |
|
Cool. Then I will prepare a PR to explore things a bit. I wanted to make sure that it wouldn't be wasted work. I think docutils is a great pipeline, and I think MyST is a neat language, so having more robust integration between the two would be very cool. |
|
Cool cheers!
Yeh I see you have been active on their repo. I've you could persuade them to move to git, that would be great 😅 |
This is part of executablebooksGH-420, an effort to make myst_parser integrate better with Docutils. * myst_parser/docutils_.py (Parser): Use new _myst_docutils_setting_tuples function to generate a settings_spec. (Parser.parse): Use new create_myst_config function to reconstruct a MdParserConfig object from a Docutils configuration object.
Describe the enhancement you'd like
I would like a way to configure MyST from
docutils.confinstead ofconf.py.Does this solve a specific problem?
I compile most of my documents using plain docutils, not Sphinx. This is because Sphinx isn't great for single-page documents: the setup process for a new document is very heavy, and it's strongly geared towards producing books, not articles or reports.
On the other hand, Docutils works great for short to medium-length single-file documents.
Being able to use Markdown instead of reST would be nice, but as far as I can tell there's no way to configure MyST from
docutils.confinstead of Sphinx'conf.py, so there's no way to enable Markdown extensions or configure MyST in any way when using the plain-Docutils pipeline.What alternatives exist?
I'm not aware of a good workaround at the moment.
The text was updated successfully, but these errors were encountered: