Support for rich formatting in documentation descriptions

[Justin Gaylor]

I've heard some internal requests for support of richer formatting of the Praxis doc browser description fields (descriptions for resource, media_type, actions, attributes, etc). I want to start this thread to get more ideas and input for what make sense to do there and how to make it happen.

One idea is to support HTML in the documentation description, but it might make more sense to support Markdown, since Praxis generates JSON, not HTML and there are generators available from Markdown to HTML (and other formats).

[alis...@rightscale.com]

Being able to link to other MediaTypes/Resources/actions/attributes from within descriptions would be nice.

[Josep Blanquer]

Allright,

 I just committed support for markdown descriptions. It is still in master, and haven't cut a new gem yet, but you can certainly give it a try.

Any description for controllers, actions, attributes, mediatypes...etc would be rendered as markdown.

Remember that, this means that HTML would render perfectly fine too.

Also, know that, if the description text starts indented with 4 spaces or more, it'll be interpreted as a code block (and therefore rendered with a surrounding code box etc). I'm just saying this since I happen to try it with an example app that had a description defined through a heredoc, which was all indented many spaces, and it took me a moment to figure that out.

@alistair linking can happen as normal markdown/html tags, obviously. What we need to formalize a little more is the routing on the doc browser, so you can easily create the hrefs to resources or types. The good news there is that the "ids" for the routes of controllers and types are consistent now, and should be very easy to construct by using their "id" method (and knowing the appropriate prefix).

Cheers,

Josep M.

On Wed, Mar 4, 2015 at 2:17 AM, <alis...@rightscale.com> wrote:

Being able to link to other MediaTypes/Resources/actions/attributes from within descriptions would be nice.

--
You received this message because you are subscribed to the Google Groups "praxis-development" group.
To unsubscribe from this group and stop receiving emails from it, send an email to praxis-developm...@googlegroups.com.
To post to this group, send email to praxis-de...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/praxis-development/55db4fdc-3bf3-4f72-900c-29e5ab58c0d4%40googlegroups.com.

For more options, visit https://groups.google.com/d/optout.

[Justin Gaylor]

Thanks Josep! The new Markdown support is a great addition to the doc browser. :)

Cheers,

Justin

On Wednesday, March 11, 2015 at 5:05:14 PM UTC-7, Josep Blanquer wrote:

Allright,

 I just committed support for markdown descriptions. It is still in master, and haven't cut a new gem yet, but you can certainly give it a try.

Any description for controllers, actions, attributes, mediatypes...etc would be rendered as markdown.

Remember that, this means that HTML would render perfectly fine too.

Also, know that, if the description text starts indented with 4 spaces or more, it'll be interpreted as a code block (and therefore rendered with a surrounding code box etc). I'm just saying this since I happen to try it with an example app that had a description defined through a heredoc, which was all indented many spaces, and it took me a moment to figure that out.

@alistair linking can happen as normal markdown/html tags, obviously. What we need to formalize a little more is the routing on the doc browser, so you can easily create the hrefs to resources or types. The good news there is that the "ids" for the routes of controllers and types are consistent now, and should be very easy to construct by using their "id" method (and knowing the appropriate prefix).

Cheers,

Josep M.

On Wed, Mar 4, 2015 at 2:17 AM, <alis...@rightscale.com> wrote:

Being able to link to other MediaTypes/Resources/actions/attributes from within descriptions would be nice.

--
You received this message because you are subscribed to the Google Groups "praxis-development" group.

To unsubscribe from this group and stop receiving emails from it, send an email to praxis-development+unsub...@googlegroups.com.

To post to this group, send email to praxis-de...@googlegroups.com.