Hello,My experience is in setting up the Pygame documentation generator under Sphinx. So all the hacks to get a unsphinx-like banner with links to all the module pages was my work.
On 16-12-16 09:59 AM, Thomas Kluyver wrote:
On 16 December 2016 at 10:12, Radomir Dopieralski <pygame@xxxxxxxxxxxx <mailto:pygame@xxxxxxxxxxxx>> wrote:My experience is that Sphinx organizes document source files in a tree structure, with a root document linking to child documents which can have children in turn. When adding a new document, the main concern is that it is added into the tree somewhere. Sphinx supports wild card patterns and directory recursion to simplify this.As for the tools, I wonder if we could just use Sphinx like all the PyGame documentation does, and not get extra tools involved.I've made websites with Sphinx before (ipython.org <http://ipython.org>), and my experience was that it's not a great tool for that task - it's designed around docs, and you have to do a fair bit to suppress docs-oriented features and checks that don't make sense for a website, such as having all the pages in a strict order for conversion to PDF.
A downside is all pages built with a particular theme share the same layout. For example, in the Pygame docs the same Jinja2 templates generate the index page, module reference pages, and tutorial pages. So if you want a sidebar on one page, you get it on all pages. And I imagine to get around this needs another level of complexity, such as multiple document trees with each tree using a different theme.