search

restful-api-description-language / RADL

RADL: A description language and tooling for hypermedia-driven RESTful APIs
Apache License 2.0
23 stars 5 forks source link

Provide alternative and external CSS stylesheet for HTML documentation #51

Closed gentlewind closed 8 years ago

gentlewind commented 8 years ago

Different organizations require different HTML layouts for the REST API documentation. The RADL tool should allow developers to choose from out-of-the-box css stylesheets, or specify a custom one during the task execution of radl2html.

jonathanrobie commented 8 years ago

Currently, the stylesheet is inlined to make it easier to handle the description as a single file. Two possible options:

  1. Parameterize the XSLT stylesheet to specify the CSS stylesheets, but continue to inline them. This allows the stylesheet to be chosen when HTML is generated.
  2. Refer to an external stylesheet that includes all CSS stylesheets to be used. This allows the stylesheet to be chosen by the user at any time, but also means that we can no longer use the description as a single file.

I'm inclined to do #1 but not #2. I prefer a single page self-contained document.

RaySinnema commented 8 years ago

+1 for single page self-contained documentation.

gentlewind commented 8 years ago

A parameter 'cssURL' will be added to Gradle/Maven/API interface of the radl2docs. It can either be a local file or a remote URL. The doc generator will inline the stylesheet into the html, so it's still a single page. The other change that is to be brought to html is the code hightlight for XML/JSON examples. I am planning to use https://github.com/google/code-prettify as the default. It is not perfect but allows extensions. I've seen that a complex html doc ususally has more than one css and/or js files, referencing by href links. So there may be further requirement to add multiple css as links.