#17 ✓closed
Ben Hood

Add HTML structure to REST documentation

Reported by Ben Hood | September 27th, 2010 @ 11:29 AM

We need to modify the template that generates the REST documentation to put in more structured HTML that can be used to style each documentation page. A example of how it should look is the Twitter API, so maybe a cue can be taken from the source code of that site. Also, it might be nice to have a permanently visible navigation on each page - I should think this is easy enough to generate either as a Jekyll template or just in the StringTemplate.

Comments and changes to this ticket

  • Michal Cudrnak

    Michal Cudrnak September 28th, 2010 @ 06:31 PM

    • State changed from “new” to “resolved”

    I've wrapped logical blocks in divs and introduced more basic formatting in a few places.

    There are some other minor tweaks such as including the full resource path (e.g. incl. /config) -- this was a bug.

    There's also a menu on every resource page with the active resource highlighted (currently just without a link). Because of this highlighting I used StringTemplate and not Jekyll to do this.

  • Ben Hood

    Ben Hood September 28th, 2010 @ 07:01 PM

    • State changed from “resolved” to “closed”

    This is looking pretty good now. The only observation I have is that the different HTML elements do not have class attributes which I assume are necessary for CSS to bind to. I would have thought that each "type" of attribute wrapped in an HTML element (e.g. optional parameter) requires it's own class.

    However, I think Sophie can make a call on this one because she will be confronted by it, so if she requires some class attributes to wander into the compiled page, let's let her make that call. She can decide whether she wants to reopen this issue, or just make the adjustments herself.

  • Michal Cudrnak

    Michal Cudrnak September 28th, 2010 @ 07:47 PM

    FYI, in CSS you can set properties for specific HTML elements or even a hierarchy (e.g. all EMs in a DIV with id=abc wrapped in a class=def element), so hopefully the brevity shouldn't affect things much.

    I kind of wanted to avoid "overdecorating" the markdown with HTML, although that's probably not a big priority. Anyway, like you're saying, the ticket can be reopened if need be.

  • Ben Hood

    Ben Hood September 28th, 2010 @ 09:02 PM

    Yes, that's a fair point. And I'm a total CSS n00b anyway, so I don't
    really have an informed opinion on this one.

Please Sign in or create a free account to add a new ticket.

With your very own profile, you can contribute to projects, track your activity, watch tickets, receive and update tickets through your email and much more.

New-ticket Create new ticket

Create your profile

Help contribute to this project by taking a few moments to create your personal profile. Create your profile ยป

A Real Time Differencing Tool.

Shared Ticket Bins

People watching this ticket

Tags

Referenced by

Pages