diff --git a/ChangeLog.md b/ChangeLog.md --- a/ChangeLog.md +++ b/ChangeLog.md @@ -1,3 +1,7 @@ +## 0.1.1 + +* Fix cabal-file to add hamlet-files + ## 0.1.0 * First Release diff --git a/templates/docs.hamlet b/templates/docs.hamlet new file mode 100644 --- /dev/null +++ b/templates/docs.hamlet @@ -0,0 +1,57 @@ +$doctype 5 + + + + #{title raml} API documentation + <meta content="IE=edge" http-equiv="X-UA-Compatible"> + <meta content="text/html; charset=utf-8" http-equiv="Content-Type"> + <meta content="https://github.com/junjihashimoto/yesod-raml #{yesodRamlDocsVersion}" name="generator"> + <link href="https://netdna.bootstrapcdn.com/bootstrap/3.1.1/css/bootstrap.min.css" rel="stylesheet"> + <link href="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/8.1/styles/default.min.css" rel="stylesheet"> + <script src="https://code.jquery.com/jquery-1.11.0.min.js" type="text/javascript"> + <script src="https://netdna.bootstrapcdn.com/bootstrap/3.1.1/js/bootstrap.min.js" type="text/javascript"> + <script src="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/8.1/highlight.min.js" type="text/javascript"> + <script type="text/javascript"> + ^{scriptBody} + <style> + ^{styleBody} + <body data-spy="scroll" data-target="#sidebar"> + <div .container> + <div .row> + <div .col-md-9 role="main"> + <div .page-header> + <h1> + #{title raml} API documentation + <small> + version #{version raml} + <p> + #{baseUri raml} + $forall doc <- documentation raml + <h3 ##{docId (doc_title doc)}> + <a href="##{docId (doc_title doc)}"> + #{doc_title doc} + ^{txt2md (doc_content doc)} + $forall (uri,resource) <- M.toList (paths raml) + <div .panel .panel-default> + <div .panel-heading> + <h3 .panel-title ##{docId uri}> + $maybe name <- r_displayName resource + #{name} + $nothing + #{uri} + <div .panel-body> + $maybe txt <- r_description resource + <div .top-resource-description> + ^{txt2md txt} + <div .panel-group> + ^{resources raml resource "" uri} + <div .col-md-3> + <div .hidden-print .affix #sidebar role="complementary"> + <ul .nav .nav-pills .nav-stacked> + $forall (uri,resource) <- M.toList (paths raml) + <li> + <a href="##{docId uri}"> + $maybe name <- r_displayName resource + #{name} + $nothing + #{uri} diff --git a/templates/item.hamlet b/templates/item.hamlet new file mode 100644 --- /dev/null +++ b/templates/item.hamlet @@ -0,0 +1,53 @@ +<li> + $maybe s <- h_displayName item + <strong> + #{s} + : + $nothing + <strong> + #{key} + : + + <em> + $maybe s <- h_required item + required + ( + $if not (null (h_enum item)) + one of #{T.intercalate "," (h_enum item)} + $else + $maybe s <- h_type item + #{s} + + $maybe s <- h_default item + - default: #{s} + $maybe s <- h_repeat item + - repeat: #{s} + $if (h_type item == Just "string") + $maybe s <- h_minLength item + - minLength: #{s} + $maybe s <- h_maxLength item + - maxLength: #{s} + $else + $maybe s <- h_minimum item + - minimum: #{s} + $maybe s <- h_maximum item + - maximum: #{s} + $maybe s <- h_pattern item + - pattern: #{s} + ) + + $maybe s <- h_description item + ^{txt2md s} + + $maybe s <- h_example item + <p> + <strong> + Example + : + $if (h_type item == Just "string") + <pre> + #{s} + $else + <pre> + <code> + #{s} diff --git a/templates/resource.hamlet b/templates/resource.hamlet new file mode 100644 --- /dev/null +++ b/templates/resource.hamlet @@ -0,0 +1,179 @@ +$if haveMethod res + <div .panel .panel-white> + <div .panel-heading> + <h4 .panel-title> + <a .collapsed data-toggle="collapse" href="#panel_#{docId (T.append puri ruri)}"> + <span .parent> + #{puri} + #{ruri} + <span .methods> + $forall (mname,method) <- M.toList (r_methods res) + <a href="##{docId (T.append puri ruri)}_#{mname}"> + $# modal shown by hashchange event + <span .badge .badge_#{mname}> + $if null (m_securedBy method) + #{mname} + $else + #{mname}<span .glyphicon .glyphicon-lock title="Authentication required"> + <div .panel-collapse .collapse #panel_#{docId (T.append puri ruri)}> + <div .panel-body> + $maybe desc <- r_description res + <div .resource-description> + ^{txt2md desc} + <div .list-group> + $forall (mname,method) <- M.toList (r_methods res) + <div .list-group-item onclick="window.location.href = '##{docId (T.append puri ruri)}_#{mname}'"> + <span .badge .badge_#{mname}> + $if null (m_securedBy method) + #{mname} + $else + #{mname}<span .glyphicon .glyphicon-lock title="Authentication required"> + <div .method_description> + $maybe desc <- m_description method + ^{txt2md desc} + <div .clearfix> + $forall (mname,method) <- M.toList (r_methods res) + <div .modal .fade ##{docId (T.append puri ruri)}_#{mname} tabindex="0"> + <div .modal-dialog> + <div .modal-content> + <div .modal-header> + <button aria-hidden="true" .close data-dismiss="modal" type="button"> + × + <h4 .modal-title #myModalLabel> + <span .badge .badge_#{mname}> + $if null (m_securedBy method) + #{mname} + $else + #{mname}<span .glyphicon .glyphicon-lock title="Authentication required"> + <span .parent> + #{puri} + #{ruri} + <div .modal-body> + $maybe desc <- m_description method + <div .alert .alert-info> + ^{txt2md desc} + + $forall securedby <- m_securedBy method + <div .alert .alert-warning> + <span .glyphicon .glyphicon-lock title="Authentication required"> + Secured by #{securedby} + $maybe scheme <- findAuth securedby raml + $maybe desc <- ss_description scheme + ^{txt2md desc} + + $# Nav tabs + <ul .nav .nav-tabs> + $if haveParam res method + <li .active> + <a data-toggle="tab" href="##{docId (T.append puri ruri)}_#{mname}_request"> + Request + + $if (not (M.null (m_responses method))) + <li> + <a data-toggle="tab" href="##{docId (T.append puri ruri)}_#{mname}_response"> + Response + + + $# Tab panes + <div .tab-content> + $if haveParam res method + + <div .tab-pane .active ##{docId (T.append puri ruri)}_#{mname}_request> + $if haveResourceParam res + <h3> + URI Parameters + <ul> + $forall (key,item) <- M.toList (r_uriParameters res <> r_baseUriParameters res) + ^{items key item} + + $if not (M.null (m_headers method)) + <h3> + Headers + <ul> + $forall (key,item) <- M.toList (m_headers method) + ^{items key item} + + $if not (M.null (m_queryParameters method)) + <h3> + Query Parameters + <ul> + $forall (key,item) <- M.toList (m_queryParameters method) + ^{items key item} + + $if not (M.null (m_body method)) + <h3> + Body + $forall (key,b) <- M.toList (m_body method) + <p> + <strong> + Type: #{key} + $if not (M.null (req_formParameters b)) + <strong> + Form Parameters + <ul> + $forall (key,item) <- M.toList (req_formParameters b) + ^{items key item} + + $maybe s <- req_schema b + <p> + <strong> + Schema + : + <pre> + <code> + #{s} + + $maybe s <- req_example b + <p> + <strong> + Example + : + <pre> + <code> + #{s} + + $if (not (M.null (m_responses method))) + <div .tab-pane ##{docId (T.append puri ruri)}_#{mname}_response> + $forall (key,response) <- M.toList (m_responses method) + <h2> + HTTP status code + <a href="http://httpstatus.es/#{key}" target="_blank"> + #{key} + $maybe desc <- res_description response + ^{txt2md desc} + + $if (not (M.null (res_headers response))) + <h3> + Headers + <ul> + $forall (key,item) <- M.toList (res_headers response) + ^{items key item} + + $if (not (M.null (res_body response))) + + <h3> + Body + $forall (key,b) <- M.toList (res_body response) + <p> + <strong> + Type: #{key} + + $maybe s <- res_schema b + <p> + <strong> + Schema + : + <pre> + <code> + #{s} + + $maybe s <- res_example b + <p> + <strong> + Example + : + <pre> + <code> + #{s} +$forall (uri,resource) <- M.toList (r_paths res) + ^{resources raml resource (T.append puri ruri) uri} diff --git a/templates/script.hamlet b/templates/script.hamlet new file mode 100644 --- /dev/null +++ b/templates/script.hamlet @@ -0,0 +1,33 @@ +\$(document).ready(function() { +\ $('.page-header pre code, .top-resource-description pre code').each(function(i, block) { +\ hljs.highlightBlock(block); +\ }); +\ +\ $('[data-toggle]').click(function() { +\ var selector = $(this).data('target') + ' pre code'; +\ $(selector).each(function(i, block) { +\ hljs.highlightBlock(block); +\ }); +\ }); +\ +\ // open modal on hashes like +\ $(window).bind('hashchange', function(e) { +\ var anchor_id = document.location.hash.substr(1); +\ var element = $('#' + anchor_id); +\ +\ // do we have such element + is it a modal? --> show it +\ if (element.length && element.hasClass('modal')) { +\ element.modal('show'); +\ } +\ }); +\ +\ // execute hashchange on first page load +\ $(window).trigger('hashchange'); +\ +\ // remove url fragment on modal hide +\ $('.modal').on('hidden.bs.modal', function() { +\ if(history && history.replaceState) { +\ history.replaceState({}, '', '#'); +\ } +\ }); +\ }); diff --git a/templates/style.hamlet b/templates/style.hamlet new file mode 100644 --- /dev/null +++ b/templates/style.hamlet @@ -0,0 +1,107 @@ +\ .hljs { +\ background: transparent; +\ } +\ .parent { +\ color: #999; +\ } +\ .list-group-item > .badge { +\ float: none; +\ margin-right: 6px; +\ } +\ .panel-title > .methods { +\ float: right; +\ } +\ .badge { +\ border-radius: 0; +\ text-transform: uppercase; +\ width: 70px; +\ font-weight: normal; +\ color: #f3f3f6; +\ line-height: normal; +\ } +\ .badge_get { +\ background-color: #63a8e2; +\ } +\ .badge_post { +\ background-color: #6cbd7d; +\ } +\ .badge_put { +\ background-color: #22bac4; +\ } +\ .badge_delete { +\ background-color: #d26460; +\ } +\ .badge_patch { +\ background-color: #ccc444; +\ } +\ .list-group, .panel-group { +\ margin-bottom: 0; +\ } +\ .panel-group .panel+.panel-white { +\ margin-top: 0; +\ } +\ .panel-group .panel-white { +\ border-bottom: 1px solid #F5F5F5; +\ border-radius: 0; +\ } +\ .panel-white:last-child { +\ border-bottom-color: white; +\ -webkit-box-shadow: none; +\ box-shadow: none; +\ } +\ .panel-white .panel-heading { +\ background: white; +\ } +\ .tab-pane ul { +\ padding-left: 2em; +\ } +\ .tab-pane h2 { +\ font-size: 1.2em; +\ padding-bottom: 4px; +\ border-bottom: 1px solid #ddd; +\ } +\ .tab-pane h3 { +\ font-size: 1.1em; +\ } +\ .tab-content { +\ border-left: 1px solid #ddd; +\ border-right: 1px solid #ddd; +\ border-bottom: 1px solid #ddd; +\ padding: 10px; +\ } +\ #sidebar { +\ margin-top: 30px; +\ padding-right: 5px; +\ overflow: auto; +\ height: 90%; +\ } +\ .top-resource-description { +\ border-bottom: 1px solid #ddd; +\ background: #fcfcfc; +\ padding: 15px 15px 0 15px; +\ margin: -15px -15px 10px -15px; +\ } +\ .resource-description { +\ border-bottom: 1px solid #fcfcfc; +\ background: #fcfcfc; +\ padding: 15px 15px 0 15px; +\ margin: -15px -15px 10px -15px; +\ } +\ .resource-description p:last-child { +\ margin: 0; +\ } +\ .list-group .badge { +\ float: left; +\ } +\ .method_description { +\ margin-left: 85px; +\ } +\ .method_description p:last-child { +\ margin: 0; +\ } +\ .list-group-item { +\ cursor: pointer; +\ } +\ .list-group-item:hover { +\ background-color: #f5f5f5; +\ } diff --git a/yesod-raml-docs.cabal b/yesod-raml-docs.cabal --- a/yesod-raml-docs.cabal +++ b/yesod-raml-docs.cabal @@ -1,5 +1,5 @@ name: yesod-raml-docs -version: 0.1.0 +version: 0.1.1 synopsis: A html documentation generator library for RAML. description: A html documentation generator library for RAML. license: MIT @@ -11,6 +11,11 @@ cabal-version: >=1.10 extra-source-files: ChangeLog.md , README.md + , templates/item.hamlet + , templates/style.hamlet + , templates/docs.hamlet + , templates/script.hamlet + , templates/resource.hamlet bug-reports: https://github.com/junjihashimoto/yesod-raml/issues