Getting started!
Brought to you by:
darklite09
Menu
▾
▴
#2 Getting started!
None
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.
Originally posted by: brechtm
docutils mirror
comment by @ericholscher:
Moving docutils over to GitHub (or GitLab) has been discussed several times over the past years. The docutils team is strongly opposed to it, and I think we should respect that decision. After all, there is no certainty that there will be more contributions to the project after such a move.
We can however set up a mirror here on GitHub to collaborate on patches using PRs (helped by CI to run the test suite). Once a PR is deemed ready (by us), we can create a new patch ticket on SourceForge and link to the PR and patch. Feedback on the patch will be handled on SourceForge, but at least Subversion is out of the equation. I feel this is a good middle ground between having the convenience of GitHub PR's while respecting the docutils team's preferences. The docutils maintainers are of course free to make use of GitHub PR reviewing feature, if they wish.
I'm not sure what to do with bug reports. We could allow people to create bug reports using GitHub issues, but I would make it clear that this is an independent project and provide a link to the docutils issue tracker on SourceForge. Should we create corresponding tickets on SF?
Perhaps we can simply run SourceForge's GitHub Importer weekly?(incremental import doesn't seem possible)friendly API overlaying docutils (docutil-utils? 😉 )
This would be independent from the docutils project and would thus not suffer from any SF/GitHub interop issues. As a start, this could simply be a collection of helper functions, e.g. to construct a table, or
convert_rst_to_nodes()from sphinx-doc/sphinx#8039.reStructuredText homepage
I'm not sure on the details, but I basically want a go-to page for reStructuredText. Perhaps something akin to the MultiMarkdown website, providing an introduction to reStructuredText along with links to resources. Similar to the reStructuredText documentation on the docutils website, but in a modern, welcoming package. Inspiration can be found here:
Perhaps it's not even necessary to have any tutorial or documentation on there, and simply link to the available resources:
Additionally, I think a discussion forum could be useful. I have the feeling most people don't go to the trouble of subscribing to mailing lists anymore.
Ticket moved from /p/restructuredtext-startup/imported-tickets/1/