Re-introduce multi-page themes

[m-baumgartner]

Although I know building new themes is not the top priority right now I feel like leaving a discussion open might help. I did like the aglio@1 multi paged themes. I think it gave a cleaner view to focus on a specific ressources. One-pagers can be painful and lack readability when you have dozens of ressources.

[kentchiu]

:+1:

[danielgtaylor]

I agree that it would be nice. Some things to consider if anybody wants to look into this:

• What current technologies would you use? Knockout.js may not be the best choice today.
• How would you handle the case where I publish a single page layout, people bookmark links to a specific resource/action, then I decide instead I want to publish a multi-page layout. Do the existing bookmark links just work or do they break?
• Ideally it would be its own template in the default theme, so you can re-use the color schemes. E.g. aglio --theme-template multi --theme-variables cyborg or something.

[jenssegers]

:+1:

Our documentation is just too big to fit on one single page.

[sangar82]

+1

[jenssegers]

Any updates on this? :)

[ghost]

Yes please, it would be nice to be able to hide API requests/responses for groups in different docs. I've tried to use includes to at least simplify on my side but the rendering is very slow. Separate pages would alleviate that issue.

[sangar82]

+1 again!

[jenssegers]

Any updates or alternatives?

[ghost]

After some exploration, it looks like we have to switch from aglio to Sphinx Doc which is better built than aglio and has support for multiple pages and indexes and has many more themes available.

@jenssegers you may want to take a look at Sphinx

[jenssegers]

@omouse It doesn't look like Sphinx supports API Blueprint.

[ghost]

@jenssegers someone's working on a plugin for api blueprint: https://pypi.python.org/pypi/sphinxcontrib-apiblueprint/0.0.1

What I ended up using is the httpdomain plugin because API Blueprint is going to go nowhere (it's a specialized markdown dialect and is difficult to work with) and it looks like this:

.. http:get:: /api/v2/tickets
   :synopsis: List all orders for an event

   Retrieves a list of all orders purchased for an event.

   :query event_id: Required, the id of an event
   :resheader Content-Type: application/json
   :statuscode 200: no errors

   **Example request**:

   .. sourcecode:: http

      GET /api/v2/tickets?event_id=0123456789012345678901234

   **Example response**:

   .. literalinclude:: api-responses/list-event-orders.json

This lets me import the JSON requests/responses and have many different examples of those to show what can be done with the API. It's far more flexible and powerful than dealing with API Blueprint.