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 <pyg...@sheep.art.pl
<mailto:pyg...@sheep.art.pl>> wrote:
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.
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.
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.