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 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 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 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 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.
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.
People watching this ticket
Tags
Referenced by
-
261
JSON Comparison in tests is platform dependent
(from [c381530301773092e19ecca771919b96a72f1b52])
Merge p...