Getting started!
Brought to you by:
darklite09
Menu
▾
▴
#1 Getting started!
open
nobody
None
2020-10-21
2020-10-20
Anonymous
No
Originally created by: brechtm
Let's use this issue to discuss how to go ahead with this. Here are some ideas to kick things off:
- build and authoritative, user-friendly homepage for reStructuredText
- user documentation
- tutorial
- reference docs
- index of tools (Sphinx, editors, IDE plugins, ...)
- developer documentation
- sphinx extension tutorial
- docutils internals
- reference docs
- user documentation
- work on more friendly API overlaying docutils
- helper functions to construct document trees
- for parsing
- for extending: directives, roles
- mirror the docutils repository on GitHub to coordinate contributions
- track issues
- reviewed PRs can be delivered to the docutils maintainers as patches
- in the event that this approach does indeed attract more contributors, the core docutils team might be convinced to make the switch to GitHub
My main concern at this point is whether we can gather enough people to make this a success. I can only spend a couple of hours a week on this myself, for example.
Originally posted by: webknjaz
Maybe @chrisjsewell would be interested in moving https://github.com/chrisjsewell/docutils under the roof of this org.
Originally posted by: webknjaz
Also, there's https://docutils.readthedocs.io/en/sphinx-docs/ — it seems to be coming from https://github.com/ericholscher/docutils by @ericholscher. I'm curious if he'll let us claim the project for the Chris' repo, for example.
Originally posted by: ericholscher
There was talk about this with the docutils maintainers over the past few months. Have they 👍'd this work? Otherwise, I worry that this will just end up as a weird fork that isn't actually maintained or merged by the core team, and that will possibly be an even worse outcome for everyone. Is the goal here to do the work and then hope it will be adopted?
Originally posted by: jdillard
I haven't jumped too far down into Docutils, but could spend a little time helping to "modernize" the reStructuredText docs. I guess to Eric's point, how much of this is intended to be a separate "unofficial" resource vs upstreamed. It sounds like potentially multiple repos, only one of which is the Docutils mirror?
Originally posted by: chrisjsewell
Well I am definitely down for improvements and very much agree with your comments https://github.com/sphinx-doc/sphinx/issues/8039#issuecomment-713015792
Personally, I don't see the current docutils maintainers ever moving away from sourceforge, despite my best efforts:
To an extent I do appreciate the effort of these maintainers, but I do feel like they are "gate-keeping" by not moving away from sourceforge 😬
I've played around with the docutils code a lot. Obviously it works, but I can tell you its no gold standard for programming and there is plenty of room for improvement (particularly for async compliance and removing the need for sphinx to have to monkey patch it).
TBH, with my myst-parser hat on, I would like to see the directive/role code and AST completely decoupled from the syntax parser. There is no reason that it needs to be dependent on the actual source syntax (Markdown > rST 😉)
In terms of the documentation, I have seen the maintainers argue that the docs should represent "vanilla" docutils, i.e. no sphinx. So again I couldn't see them actually deprecating their existing documentation in favour of anything new.
I agree with you though that this is very detrimental to the user experience (and its such a pain to always have to add docutils classes to nitpick ignore for intersphinx).
I think at least maintaining separate documentation would be very worthwhile, even if it is not "officially" supported.
I'm happy to move https://github.com/chrisjsewell/docutils wherever. I've already got maintainer priveledges to https://github.com/docutils/docutils from @ericholscher, with the intention to move it there. The sticking point was that its easy to create a "static" mirror of docutils from sourceforge, but ideally it should be dynamically updated (probably via a GH action cron job) which was a trickier prospect that I haven't yet had the time to figure out.