go-slate

go-slate

go-slate is a CLI tool to generate API documentation using brilliant Slate layout by Robert Lord. go-slate contains bundled Slate (including Kittn API Example Documentation) and requires no additional software to install.

go-slate can also generate a Go package with embedded documentation to include into Go binary. A simple HTTP(S) server to serve rendered documentation is also provided.

Why

Slate is arguably the best tool around to quickly hack an API documentation which will look really good. However it uses Ruby bundler and brings loads of software which did not go well with my Mac. Besides, I really got used to Go all you need is a single binary way of things.

There were also Hugo DocuAPI theme (based on Slate, too), but it has its own drawbacks, mostly because of different ways middleman and backfriday render contents.

So I quickly hacked go-slate.

Installation

$ go get -u github.com/wireleap/go-slate

How to start

Assuming following source tree

src
└── service
    ├── main.go
    └── apidoc

the typical usage would be:

1. Extract template content

go-slate extract src/service/apidoc contents

1. Now edit apidoc/index.html.md and add following lines to your main.go:

//go:generate go-slate package apidoc internal/apidoc

package main

import (
    "net/http"
    "fmt"
    "service/internal/apidoc"
)

func main() {
    http.HandleFunc("/help/", apidoc.HTTPHandlerWithPrefix("/help"))
    //...
    if err := http.ListenAndServe(":8080", nil); err != nil{
        fmt.Println(err)
    }
}

1. Generate package with embedded documentation

go generate service
go build service

1. Enjoy beautiful documentation at http://service:8080/help/

Usage

go-slate [command]

Available commands:

help        Help about any command
extract     extracts slate files bundled with go-slate to specified directory
package     produces an embeddable package with rendered documentation content and HTTP handler
site        renders documentation from source directory to output directory
server      serves rendered API documentation over HTTP(S)
version     prints version

Extact

go-slate extract [directory] [components to extract...]

Extracts Slate files bundled with go-slate to a specified directory. With none components supplied, extracts only slate example documentation project content (Markdown files). Otherwise, a specified list of components will be extracted. The component name might be either file name or one of

• all
• contents
• layouts
• stylesheets
• javascripts
• images

To list bundled Slate contents, use go-slate extract -l

Rendering commands options

Commands site, package and server render content and share a set of options

--no-minify css|jss|html|all

Disables compact output for a specific type of content. Multiple options can be listed with comma.

--logo

Defines a logo file to use, overriding default or setting in document preamble. Use word none to disable logo block completely.

--rtl and --no-rtl

Enables or disable Right-to-left scripts support, overriding default (no) or setting in document preamble.

--search and --no-search

Enables or disable Slate search block, overriding setting in document preamble.

--style file

Loads an SCSS style to adjust Slate styles. Note that this adds to, and not override document preamble option style. A list of available variables can be obtained by go-slate extract . stylesheets/_variables.scss

Site

go-slate site [source directory] [output directory] [flags]

Renders documentation to a destination.

Package

go-slate package [source directory] [resulting package directory] [flags]

Produces an embeddable Go package using go-imbed

--pkg name

By default, package takes package name from the last path item of resulting package directory. This option sets package name explicitly.

--work-dir directory

By default, package renders content in a temporary directory and removes it afterwards. This option tells go-slate to use specified directory and keep content afterwards.

Server

go-slate server [source directory] [address to listen at] [flags]

Starts an HTTP server listening at the specified address and serving rendered content.

--tls-cert file and --tls-key file

If both options are specified, server will serve HTTPS.

--monitor-changes

Monitor changes of source content and re-render if necessary. Any rendering error will be printed to stdout.

(A neat trick: go-slate server <empty directory> :8080 will serve the Slate example Kittn API Documentation)

Slate preamble options

go-slate supports Slate preamble options:

# document title
title: API Reference 

# must be one of supported by https://github.com/alecthomas/chroma
language_tabs: 
  - shell
  - ruby
  - python
  - javascript

# a list of footers to place under TOC navigation menu
toc_footers:  
  - <a href='#'>Sign Up for a Developer Key</a>
  - <a href='https://github.com/lord/slate'>Documentation Powered by Slate</a>

# a list of files to include from includes directory.
# files must be named as includes/_<name>.md
includes:
  - errors

# enable search block
search: true 

In addition, go-slate defines a few others:

# a logo file to use. file must be located 
# in directory images. Use `none` to disable logo
logo: logo.png    

# enable RTL support
enable_rtl: true  

# use code highlight style, must be supported by  https://github.com/alecthomas/chroma
highlight_style: monokai

# plain html to add to html <head> _before_ all Slate stylesheets and javascripts references
html_premble: |
    <link rel="stylesheet" href="https://cdn.rawgit.com/tonsky/FiraCode/1.204/distr/fira_code.css">

# An SCSS header to adjust Slate CSS
# A list of available variables can be obtained by go-slate extract . stylesheets/_variables.scss
style: |
    %default-font {
      font-family: "Fira Code", -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Helvetica, Arial, sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol";
      font-size: 14px;
    }
    

What go-slate is not

go-slate solves a very basic task and tries to be as simple and unobtrusive as possible. It is not, by any mean, a generic site generator. Use Hugo for that.

License

The MIT License, see LICENSE.md.

The embedded Slate is licensed under Apache 2.0 License, which can be extracted with go-slate extract . LICENSE command.

Special thanks

• Slate for the great API documentation layout
• Hugo DocuAPI theme for inspiration
• Blackfriday Mardown engine for Go
• Chroma the syntax highlighter for Go
• go-libsass the LibSass Go bindings
• Steve Francia for cobra, pflags and afero