Commit dd839fdf authored by Nathan Harris's avatar Nathan Harris

45 -- Add API Documentation

Motivation:

Users need a quick reference available online that is up to date.

Modifications:

Add CI job to generate and publish API docs with Jazzy

Result:

Users can view API docs that are updated when new releases are tagged at https://mordil.gitlab.io/swift-redis-nio-client
parent 6f6fe74c
Pipeline #65113411 passed with stages
in 4 minutes and 20 seconds
......@@ -8,9 +8,28 @@ pages:
only:
- tags
tags:
- private-xcode
script:
- "echo 'TODO #45 -- Publish API Docs'"
- private-macOS
script: |
version=$(git describe --abbrev=0 --tags || echo "0.0.0")
swift build
sourcekitten doc --spm-module "RedisNIO" > ./RedisNIO.json
swift package generate-xcodeproj
jazzy --clean \
--author "Nathan Harris (Mordil)" \
--readme "./README.md" \
--author_url "https://mordil.info" \
--github_url "https://gitlab.com/mordil/swift-redis-nio-client" \
--github-file-prefix https://gitlab.com/mordil/swift-redis-nio-client/blob/$version \
--root-url "https://mordil.gitlab.io/swift-redis-nio-client/docs/RedisNIO" \
--module "RedisNIO" \
--module-version "$version" \
--theme fullwidth \
--xcodebuild-arguments -scheme,swift-redis-nio-client-Package \
--sourcekitten-sourcefile "./RedisNIO.json" \
--output "./public"
artifacts:
paths:
- public
.build:
stage: build release
......
/* Credit to https://gist.github.com/wataru420/2048287 */
.highlight {
.c { color: #999988; font-style: italic } /* Comment */
.err { color: #a61717; background-color: #e3d2d2 } /* Error */
.k { color: #000000; font-weight: bold } /* Keyword */
.o { color: #000000; font-weight: bold } /* Operator */
.cm { color: #999988; font-style: italic } /* Comment.Multiline */
.cp { color: #999999; font-weight: bold } /* Comment.Preproc */
.c1 { color: #999988; font-style: italic } /* Comment.Single */
.cs { color: #999999; font-weight: bold; font-style: italic } /* Comment.Special */
.gd { color: #000000; background-color: #ffdddd } /* Generic.Deleted */
.gd .x { color: #000000; background-color: #ffaaaa } /* Generic.Deleted.Specific */
.ge { color: #000000; font-style: italic } /* Generic.Emph */
.gr { color: #aa0000 } /* Generic.Error */
.gh { color: #999999 } /* Generic.Heading */
.gi { color: #000000; background-color: #ddffdd } /* Generic.Inserted */
.gi .x { color: #000000; background-color: #aaffaa } /* Generic.Inserted.Specific */
.go { color: #888888 } /* Generic.Output */
.gp { color: #555555 } /* Generic.Prompt */
.gs { font-weight: bold } /* Generic.Strong */
.gu { color: #aaaaaa } /* Generic.Subheading */
.gt { color: #aa0000 } /* Generic.Traceback */
.kc { color: #000000; font-weight: bold } /* Keyword.Constant */
.kd { color: #000000; font-weight: bold } /* Keyword.Declaration */
.kp { color: #000000; font-weight: bold } /* Keyword.Pseudo */
.kr { color: #000000; font-weight: bold } /* Keyword.Reserved */
.kt { color: #445588; } /* Keyword.Type */
.m { color: #009999 } /* Literal.Number */
.s { color: #d14 } /* Literal.String */
.na { color: #008080 } /* Name.Attribute */
.nb { color: #0086B3 } /* Name.Builtin */
.nc { color: #445588; font-weight: bold } /* Name.Class */
.no { color: #008080 } /* Name.Constant */
.ni { color: #800080 } /* Name.Entity */
.ne { color: #990000; font-weight: bold } /* Name.Exception */
.nf { color: #990000; } /* Name.Function */
.nn { color: #555555 } /* Name.Namespace */
.nt { color: #000080 } /* Name.Tag */
.nv { color: #008080 } /* Name.Variable */
.ow { color: #000000; font-weight: bold } /* Operator.Word */
.w { color: #bbbbbb } /* Text.Whitespace */
.mf { color: #009999 } /* Literal.Number.Float */
.mh { color: #009999 } /* Literal.Number.Hex */
.mi { color: #009999 } /* Literal.Number.Integer */
.mo { color: #009999 } /* Literal.Number.Oct */
.sb { color: #d14 } /* Literal.String.Backtick */
.sc { color: #d14 } /* Literal.String.Char */
.sd { color: #d14 } /* Literal.String.Doc */
.s2 { color: #d14 } /* Literal.String.Double */
.se { color: #d14 } /* Literal.String.Escape */
.sh { color: #d14 } /* Literal.String.Heredoc */
.si { color: #d14 } /* Literal.String.Interpol */
.sx { color: #d14 } /* Literal.String.Other */
.sr { color: #009926 } /* Literal.String.Regex */
.s1 { color: #d14 } /* Literal.String.Single */
.ss { color: #990073 } /* Literal.String.Symbol */
.bp { color: #999999 } /* Name.Builtin.Pseudo */
.vc { color: #008080 } /* Name.Variable.Class */
.vg { color: #008080 } /* Name.Variable.Global */
.vi { color: #008080 } /* Name.Variable.Instance */
.il { color: #009999 } /* Literal.Number.Integer.Long */
}
This diff is collapsed.
window.jazzy = {'docset': false}
if (typeof window.dash != 'undefined') {
document.documentElement.className += ' dash'
window.jazzy.docset = true
}
if (navigator.userAgent.match(/xcode/i)) {
document.documentElement.className += ' xcode'
window.jazzy.docset = true
}
function toggleItem($link, $content) {
var animationDuration = 300;
$link.toggleClass('token-open');
$content.slideToggle(animationDuration);
}
function itemLinkToContent($link) {
return $link.parent().parent().next();
}
// On doc load + hash-change, open any targetted item
function openCurrentItemIfClosed() {
if (window.jazzy.docset) {
return;
}
var $link = $(`.token[href="${location.hash}"]`);
$content = itemLinkToContent($link);
if ($content.is(':hidden')) {
toggleItem($link, $content);
}
}
$(openCurrentItemIfClosed);
$(window).on('hashchange', openCurrentItemIfClosed);
// On item link ('token') click, toggle its discussion
$('.token').on('click', function(event) {
if (window.jazzy.docset) {
return;
}
var $link = $(this);
toggleItem($link, itemLinkToContent($link));
// Keeps the document from jumping to the hash.
var href = $link.attr('href');
if (history.pushState) {
history.pushState({}, '', href);
} else {
location.hash = href;
}
event.preventDefault();
});
// Clicks on links to the current, closed, item need to open the item
$("a:not('.token')").on('click', function() {
if (location == this.href) {
openCurrentItemIfClosed();
}
});
$(function(){
var $typeahead = $('[data-typeahead]');
var $form = $typeahead.parents('form');
var searchURL = $form.attr('action');
function displayTemplate(result) {
return result.name;
}
function suggestionTemplate(result) {
var t = '<div class="list-group-item clearfix">';
t += '<span class="doc-name">' + result.name + '</span>';
if (result.parent_name) {
t += '<span class="doc-parent-name label">' + result.parent_name + '</span>';
}
t += '</div>';
return t;
}
$typeahead.one('focus', function() {
$form.addClass('loading');
$.getJSON(searchURL).then(function(searchData) {
const searchIndex = lunr(function() {
this.ref('url');
this.field('name');
this.field('abstract');
for (const [url, doc] of Object.entries(searchData)) {
this.add({url: url, name: doc.name, abstract: doc.abstract});
}
});
$typeahead.typeahead(
{
highlight: true,
minLength: 3,
autoselect: true
},
{
limit: 10,
display: displayTemplate,
templates: { suggestion: suggestionTemplate },
source: function(query, sync) {
const lcSearch = query.toLowerCase();
const results = searchIndex.query(function(q) {
q.term(lcSearch, { boost: 100 });
q.term(lcSearch, {
boost: 10,
wildcard: lunr.Query.wildcard.TRAILING
});
}).map(function(result) {
var doc = searchData[result.ref];
doc.url = result.ref;
return doc;
});
sync(results);
}
}
);
$form.removeClass('loading');
$typeahead.trigger('focus');
});
});
var baseURL = searchURL.slice(0, -"search.json".length);
$typeahead.on('typeahead:select', function(e, result) {
window.location = baseURL + result.url;
});
});
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
{{#deprecation_message}}
<div class="aside aside-deprecated">
<p class="aside-title">Deprecated</p>
{{{deprecation_message}}}
</div>
{{/deprecation_message}}
{{#unavailable_message}}
<div class="aside aside-unavailable">
<p class="aside-title">Unavailable</p>
{{{unavailable_message}}}
</div>
{{/unavailable_message}}
<!DOCTYPE html>
<html lang="en">
<head>
<title>{{name}} {{kind}} Reference</title>
<link rel="stylesheet" type="text/css" href="{{path_to_root}}css/jazzy.css" />
<link rel="stylesheet" type="text/css" href="{{path_to_root}}css/highlight.css" />
<meta charset="utf-8">
<script src="{{path_to_root}}js/jquery.min.js" defer></script>
<script src="{{path_to_root}}js/jazzy.js" defer></script>
{{{custom_head}}}
{{^disable_search}}
<script src="{{path_to_root}}js/lunr.min.js" defer></script>
<script src="{{path_to_root}}js/typeahead.jquery.js" defer></script>
<script src="{{path_to_root}}js/jazzy.search.js" defer></script>
{{/disable_search}}
</head>
<body>
{{#dash_type}}
<a name="//apple_ref/{{language_stub}}/{{dash_type}}/{{name}}" class="dashAnchor"></a>
{{/dash_type}}
<a title="{{name}} {{kind}} Reference"></a>
{{> header}}
<p class="breadcrumbs">
<a class="breadcrumb" href="{{path_to_root}}index.html">{{module_name}} Reference</a>
<img class="carat" src="{{path_to_root}}img/carat.png" />
{{name}} {{kind}} Reference
</p>
<div class="content-wrapper">
{{> nav}}
<article class="main-content">
<section class="section">
<div class="section-content">
{{^hide_name}}<h1>{{name}}</h1>{{/hide_name}}
{{> deprecation}}
{{#declaration}}
<div class="declaration">
<div class="language">
{{{declaration}}}
</div>
</div>
{{/declaration}}
{{{overview}}}
</div>
</section>
{{> tasks}}
</article>
</div>
{{> footer}}
</body>
</div>
</html>
<section class="footer">
{{{copyright}}}
<p>Generated by <a class="link" href="https://github.com/realm/jazzy" target="_blank" rel="external">jazzy ♪♫ v{{jazzy_version}}</a>, a <a class="link" href="https://realm.io" target="_blank" rel="external">Realm</a> project.</p>
</section>
<header class="header">
<p class="header-col header-col--primary">
<a class="header-link" href="{{path_to_root}}index.html">
{{module_name}} Docs
</a>
{{#doc_coverage}} ({{doc_coverage}}% documented){{/doc_coverage}}
</p>
{{^disable_search}}
<p class="header-col--secondary">
<form role="search" action="{{path_to_root}}search.json">
<input type="text" placeholder="Search documentation" data-typeahead>
</form>
</p>
{{/disable_search}}
{{#github_url}}
<p class="header-col header-col--secondary">
<a class="header-link" href="{{github_url}}">
<img class="header-icon" src="{{path_to_root}}img/gl.png"/>
View on GitLab
</a>
</p>
{{/github_url}}
{{#dash_url}}
<p class="header-col header-col--secondary">
<a class="header-link" href="{{dash_url}}">
<img class="header-icon" src="{{path_to_root}}img/dash.png"/>
Install in Dash
</a>
</p>
{{/dash_url}}
</header>
<nav class="navigation">
<ul class="nav-groups">
{{#structure}}
<li class="nav-group-name">
<a class="nav-group-name-link" href="{{path_to_root}}{{url}}">{{section}}</a>
<ul class="nav-group-tasks">
{{#children}}
<li class="nav-group-task">
<a class="nav-group-task-link" href="{{path_to_root}}{{url}}">{{name}}</a>
</li>
{{/children}}
</ul>
</li>
{{/structure}}
</ul>
</nav>
<tr>
<td>
<code>
<em>{{name}}</em>
</code>
</td>
<td>
<div>
{{{discussion}}}
</div>
</td>
</tr>
<div class="task-group">
{{#name}}
<div class="task-name-container">
<a name="/{{uid}}"></a>
<a name="//apple_ref/{{language_stub}}/Section/{{name}}" class="dashAnchor"></a>
<a href="#/{{uid}}">
<h3 class="section-name">{{name}}</h3>
</a>
</div>
{{/name}}
<ul class="item-container">
{{#items}}
<li class="item">
<div>
<code>
<a name="/{{usr}}"></a>
<a name="//apple_ref/{{language_stub}}/{{dash_type}}/{{name}}" class="dashAnchor"></a>
{{#direct_link}}
<a class="direct-link" href="{{url}}">{{name}}</a>
</code>
{{/direct_link}}
{{^direct_link}}
{{^usage_discouraged}}
<a class="token" href="#/{{usr}}">{{name}}</a>
{{/usage_discouraged}}
{{#usage_discouraged}}
<a class="token discouraged" href="#/{{usr}}">{{name}}</a>
{{/usage_discouraged}}
</code>
{{#default_impl_abstract}}
<span class="declaration-note">
Default implementation
</span>
{{/default_impl_abstract}}
{{#from_protocol_extension}}
<span class="declaration-note">
Extension method
</span>
{{/from_protocol_extension}}
</div>
<div class="height-container">
<div class="pointer-container"></div>
<section class="section">
<div class="pointer"></div>
{{> deprecation}}
{{#abstract}}
<div class="abstract">
{{{abstract}}}
{{#url}}
<a href="{{{path_to_root}}}{{{url}}}" class="slightly-smaller">See more</a>
{{/url}}
</div>
{{/abstract}}
{{#default_impl_abstract}}
<h4>Default Implementation</h4>
<div class="default_impl abstract">
{{{default_impl_abstract}}}
</div>
{{/default_impl_abstract}}
{{#declaration}}
<div class="declaration">
<h4>Declaration</h4>
<div class="language">
<p class="aside-title">{{language}}</p>
{{{declaration}}}
</div>
{{#other_language_declaration}}
<div class="language">
<p class="aside-title">Swift</p>
{{{other_language_declaration}}}
</div>
{{/other_language_declaration}}
</div>
{{/declaration}}
{{#parameters.count}}
<div>
<h4>Parameters</h4>
<table class="graybox">
<tbody>
{{#parameters}}
{{> parameter}}
{{/parameters}}
</tbody>
</table>
</div>
{{/parameters.count}}
{{#return}}
<div>
<h4>Return Value</h4>
{{{return}}}
</div>
{{/return}}
{{#github_token_url}}
<div class="slightly-smaller">
<a href="{{{github_token_url}}}">Show on GitHub</a>
</div>
{{/github_token_url}}
</section>
{{/direct_link}}
</div>
</li>
{{/items}}
</ul>
</div>
{{#tasks.count}}
<section class="section">
<div class="section-content">
{{#tasks}}
{{> task}}
{{/tasks}}
</div>
</section>
{{/tasks.count}}
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment