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]. 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.
