Use waliki to render sphinx documents

[ostrokach]

I would like to request some input for a very hand-wavy idea that I have about combining waliki and Sphinx. Would this be very difficult to implement? Could you suggest a good place to start?

Motivation

Many people I work with use Sphinx for documenting Python projects and for making notes. For the most part, it's been working well. Sphinx makes it easy to create a table of contents, to reference other sections, to search through the documentation, to make a glossary, etc., and it comes with many nice themes.

However, using Sphinx becomes cumbersome when multiple people are working on the same "wiki" type of website. You have to use git pull / git merge to make even the smallest change, and then git pull on the webserver to update the website.

Switching to waliki greatly improves the workflow, since people can make changes directly on the website. However, you lose all the directives and other goodies that Sphinx provides, and documents written with Sphinx and with waliki are not directly compatible.

Ideally, I would like to use waliki for page creation and editing, and for tracking changes (keeping the "Waliki" bar at the top of the page, and keeping the "edit" button), but would use Sphinx to render the website. I think such a tool would be a welcome addition to the Sphinx ecosystem.

Relevant projects

Three projects I found that may be relevant are django-sphinxdoc, ablog, and sphinx-autobuild.

django-sphinxdoc allows you to embed Sphinx documentation inside a django website. However, it is cumbersome to use, and it does not allow you to use Sphinx themes or to create and edit documents.

ablog is a blogging engine that built on top of Sphinx. After all the blog-related pre-processing, it uses:

from sphinx import main
main(argv)

to generate the website (inside ablog/commands.py). Maybe waliki could do something like this as well?

sphinx-autobuild allows you instantly view the changes you make to the Sphinx documentation. Maybe we could use some of its codebase to update the webpage after you make changes to a file?

[mgaitan]

@ostrokach I'm sorry for answer this so late and thank you very much for your dedication writting it.
I perfectly understand your use case and I agree with the idea of "waliki" as a "easy frontend" for sphinx.

As far as I know, isn't easy to replace the standard docutils render with the sphinx engine, mainly because sphinx adds the "cross reference" between multiples documents.

However, should be easier to "mimic" the sphinx behaviour, supporting as many special directives/roles from sphinx into Waliki.

This is the approach that uses Nikola, for example, and in fact we should just steal its code.

Can you code a bit? Are you willing to help?