Seikichi looks promizing. I would first try to join it. Yes, there is some work to do, but you won't have less work if you start from scratch.
Luc On 13/12/16 04:54, Michael Gielda wrote: > Hi everyone, > > I wanted to spark up a discussion about reaching out further with Sphinx > by an activity not strictly related to Sphinx development per se, but in > my opinion in reality very much interdependent with the framework. > > Over the years using Sphinx I have found its use of reStructuredText > mostly a blessing but also a little bit of a curse. It's a very powerful > and extensible format, and as such very well suited to complex, > technical documents. But some of its aspects are quite quirky (smaller > problem), and most project/code management frameworks (GitLab, Redmine, > GitHub, Bitbucket) that I use which for me double as 'online review > frameworks' have limited support of it (bigger problem). That is, thanks > to the availability of some ruby parsers, the support is there in > general, but it's limited as opposed to Markdown, which is a first-class > citizen on the Web. Notably, Sphinx roles are not supported anywhere, so > any less "rSTy" and more "Sphinxy" type of documentation will render > very badly anyway (or throw 'role not found' errors), reducing the > usability of the parser in the first place. > > This is of course arguable, but I think that the reason for Markdown's > popularity at least partly has been the plethora of JavaScript > implementations which just made it spread over the web like a virus. Of > course, it's great for short documents, but as soon as you add > complexity, it just collapses (which is a shame but I've never been able > to build anything bigger with Markdown). MkDocs is OK but I find Sphinx > better feature- and stability-wise. > > It would be awesome to have some more Web support for Sphinx, and I > believe this would happen if we had a simple yet extendible javascript > parser where e.g. custom roles could be implemented. This would in turn > spawn editors, IDEs, online tooling etc, which would popularise Sphinx > itself. > > The online editor at http://rst.ninjs.org/ is nice as a demo but not > really practical as it is not a client-side solution. > AsciiDoctor has https://github.com/asciidoctor/asciidoctor.js which - > even if a bit hacky (in the sense of being a conversion of the original > code to JavaScript, not a reimplementation) - works quite well (see > https://asciidoclive.com/edit/scratch/1). No server side code there as > far as I can see. > > I haven't seen any advanced effort in that direction - the only project > that addresses the problem (but does not solve it yet) is > https://github.com/seikichi/restructured - it does offer basic support > but the sheer number of empty tickboxes shows that there is still a > long, long way to go. > > Of course, question is, why don't I write it myself. Answer: I'm no > JavaScript guru, neither am I a seasoned parser writer - but I can > assist in all sort of documentation, debug and testing activity, as > probably can my team (we have tons of RST writeup we work with on a > daily basis). [by the way - I had once tried converting the docutils > code to js with a converter, but it's just huge... gave up quite quick] > > My question is, whether there are more like-minded people out there who > too think this would be beneficial. Or perhaps I am omitting something > important, or not understanding things well enough? > Perhaps we could support seikichi, or spawn another, joint effort, at > least loosely endorsed by the Sphinx community? > > Best regards, > Michael > > -- > You received this message because you are subscribed to the Google > Groups "sphinx-users" group. > To unsubscribe from this group and stop receiving emails from it, send > an email to [email protected] > <mailto:[email protected]>. > To post to this group, send email to [email protected] > <mailto:[email protected]>. > Visit this group at https://groups.google.com/group/sphinx-users. > For more options, visit https://groups.google.com/d/optout. -- You received this message because you are subscribed to the Google Groups "sphinx-users" group. To unsubscribe from this group and stop receiving emails from it, send an email to [email protected]. To post to this group, send email to [email protected]. Visit this group at https://groups.google.com/group/sphinx-users. For more options, visit https://groups.google.com/d/optout.
