Re-introduce multi-page themes

danielgtaylor / aglio

An API Blueprint renderer with theme support that outputs static HTML

4.75k stars 480 forks source link

Re-introduce multi-page themes #186

Open m-baumgartner opened 8 years ago

m-baumgartner commented 8 years ago

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 commented 8 years ago

:+1:

danielgtaylor commented 8 years ago

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 commented 8 years ago

:+1:

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

sangar82 commented 8 years ago

jenssegers commented 8 years ago

Any updates on this? :)

ghost commented 8 years ago

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 commented 8 years ago

+1 again!

jenssegers commented 8 years ago

Any updates or alternatives?

ghost commented 8 years ago

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 commented 8 years ago

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

ghost commented 8 years ago

@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.