Hi Luc, Absolutely, of course the preferred way is to build on something existing - but I was curious if someone had any other ideas.
For this implementation to be useful, I think we need at least tables, hyperlinks, and directives in general. So, is there anyone else who'd like to contribute ;) ? Michael On Tuesday, 13 December 2016 07:26:42 UTC+1, Luc Saffre wrote: > > 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] <javascript:> > > <mailto:[email protected] <javascript:>>. > > To post to this group, send email to [email protected] > <javascript:> > > <mailto:[email protected] <javascript:>>. > > 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.
