sphinxcontrib-editable¶
In-line editable documentation
Overview¶
I read a conversation which discusses the advantages of Google Docs over traditional markup documentation because it lets users provide corrections and feedback inline. One notable section:
it’s a dynamic and collaborative experience. It’s a living process. It makes it trivially easy for anyone, with or without an account, with or without programming skills, to update the content and collaborate with me on it, in-context. To pop in a correction for a wrong number (so many corrections so far!). To reword a phrase poorly constructed (thank you readers!). The experience is substantially distinct and better than a wiki as well, especially if you have non-technical readers. Comments and suggestions are treated differently than content, and integrated with a notification system via email. There’s no awkward syntax to learn. Even technical users have a difficult time keeping wikis up-to-date! I’m witnessing it daily, both in the OSS world and in the commercial sphere. Maintaining up-to-date docs is REALLY difficult for engineers. Here … well you just make the edit right there in front of your eyes as you notice something that needs a change and an email is automatically sent to the author.
These sound like important benefits of using Google Docs. But I want to write my docs in a markup language because it’s much more flexible. So my ideal documentation system would have several features:
- Maintainers can write docs in a powerful markup language.
- Users can edit the docs in-line as they’re reading, without needing to log in or know reStructuredText.
- Users can comment on the docs with points of clarification. (sphinxcontrib-disqus provides a comments section at the bottom of the page, but no in-line comments. This is still a missing piece.)
This library demos no-login editing capability for Sphinx docs.
Live demo¶
Try out a live demo here.
Install¶
Install this package:
pip install sphinxcontrib-editable
And in docs/conf.py
add
extensions = ['sphinxcontrib.editable']