What advantages/disadvantages are there to having both a wiki view and a Sphinx view?

[westurner]

Advantages

• Beautiful Sphinx output: https://github.com/westurner/wiki/blob/master/conf.py
  • Search
  • Context-focused pages
  • Navbar
  • Responsive CSS Freedom; for my cell phone
• Pull Requests

Challenges / Disadvantages

• New wiki pages created through the GitHub wiki interface add the .rest suffix, rather than .rst
  • Sort of an advantage (.rest files are docutils-only)
  • This precludes inclusion of the wiki pages into a standard Sphinx docset as a submodule or subtree.
• Sphinx ReStructuredText is a superset of GitHub ReStructuredText (docutils), so Sphinx markup is, in the best case not supported, and in the worst case breaks the wiki render
  • Notably: :ref:, .. index:, and .. toctree:: are only supported by Sphinx
  • To test this: make rst2html_all
• Double Tables of Contents (Why are there two Tables of Contents in the Sphinx renders? #4)
• Double pulls and pushes (make pull push): https://github.com/westurner/wiki/blob/master/Makefile
• Sphinx requires a manual build step in order to publish in-progress changes

[westurner]

From a given source .rest file:

• https://github.com/westurner/wiki/blob/master/workflow.rest
• https://raw.githubusercontent.com/westurner/wiki/master/workflow.rest

There's the GitHub wiki view, which does not add a TOC sidebar, necessitating an explicit .. contents:: directive.

• https://github.com/westurner/wiki/wiki/workflow

And there's the gh-pages Sphinx-rendered view, which does have TWO Tables of Contents (see: #4):

• https://westurner.github.io/wiki/workflow