[Ruby] Procedure when using API Document tool called slate and aglio

4 minute read

Introduction

Here are the steps and impressions when you actually touched the tools slate, ʻaglio` when creating the API Document page.

About slate

You can write a document with markdown in Tools for creating API documents created with ruby.

slate installation procedure

** 1 Repository preparation **
Open the Home Repository (https://github.com/slatedocs/slate) and click use this template to create a repository anywhere.

Git clone the created repository to your local environment.

** 2 Development environment setup **
As you can see by looking at README.md, the following three startup methods are prepared.
* Natively
* Using Vagrant
* Using Docker

The procedure is also described in here and it is very kind.

This time I would like to try the steps of Natively and ʻUsing Docker`.

** 2-1 Natively (install directly to local environment) procedure **
Follow the steps described here (https://github.com/slatedocs/slate/wiki/Using-Slate-Natively).

  • In my environment, the development environment for Ruby and nodejs was ready, so I omitted the install part.
cd slate

bundle install

#middleman makes it easy to generate static sites with ruby gems
bundle exec middleman server

that’s all!

with this
http://localhost:4567/
When you access, the following API Document template will be displayed.

スクリーンショット 2020-07-26 19.55.51.jpg

** 2-2 Using Docker steps **
Follow the steps described here [https://github.com/slatedocs/slate/wiki/Using-Slate-in-Docker).

cd slate

docker build . -t slate

docker run -d --rm --name slate -p 4567:4567 -v $(pwd)/build:/srv/slate/build -v $(pwd)/source:/srv/slate/source slate

With the above, just like Natively
http://localhost:4567/
When you access, the API Document template is displayed.

The markdown file is in the source directory, so rewrite it if you want to modify the contents of the document.

** 3 Deploy procedure **
Here, try deploying according to the procedure described in here.
The procedure described here is to publish to GitHub Pages, and the execution method is just to execute the following command.

./deploy.sh

Only this!

Now that your GitHub Pages project site is open to the public, check it out.
The URL is http://yourusername.github.io/slate.
My GitHub Pages that I actually deployed is here.

If you look at the contents of deploy.sh easily

bundle exec middleman build --clean

Create a static file from the markdown file under the build directory.
スクリーンショット 2020-07-31 19.39.43.jpg

It then pushes the contents of the build directory to the gh-pages branch.

Next, I will describe aglio.

About aglio

aglio is a tool that converts files written in API Blueprint to html.

API Blueprint
API Blueprint is a language for expressing the specifications of Web API. It has various grammars for expressing API specifications. The writing style is the same as Markdown, so the writing style is also familiar.

aglio installation procedure

** 1 Repository preparation **
Create any repository on GitHub.
(Example: https://github.com/Nobuo-Hirai/api-document-use-aglio)
git clone the repository you created.

** 2 Development environment setup **
** Create directories and files for document. ** **
Create a md directory directly under root and create a markdown file for document in it.

  • Dockerfile, docker-compose.yml, build directory and deploy.sh will be explained later, so they are not necessary at this stage.

スクリーンショット 2020-07-31 20.11.49.jpg

** Create Dockerfile and docker-compose.yml for building the environment. ** **

Dockerfile

FROM node:latest

WORKDIR /projects

RUN npm install -g aglio --unsafe-perm

docker-compose.yml

docker-compose.yml


version: '3'

services:
  aglio:
    build: .
    ports:
      - '4000:4000'
    volumes:
      - './md:/projects'
      - './:/docs'
    tty: true
    #You can decide the theme when creating html.
    # https://github.com/danielgtaylor/aglio#example-output
    command: aglio --theme-variables default --theme-template triple -i index.md -s -h 0.0.0.0 -p 4000

** Build and start docker container. ** **

docker-compose up --build

With the above http: // localhost: 4000 /
When you access, you should see the API Document template as shown below.

スクリーンショット 2020-07-31 21.10.33.jpg

Modify the markdown file under the md directory and create an API document.

** 3 Creating a static file **
Run the following command to create a static file for deploy.

#Execute the command to generate html in the container
docker-compose exec aglio bash

aglio --theme-variables default --theme-template triple -i index.md -o ../docs/index.html

You should now have a ʻindex.html` file.
Next, I would like to deploy to GitHub Pages this time as well.

** 4 Create deploy.sh **
Here, we will utilize the deploy.sh used in slate.
Copy the deploy.sh used in slate and place it directly under root.

The correction points are as follows.


## slate
run_build() {
  bundle exec middleman build --clean
}
↓
↓
##Rewrite as below for aglio
run_build() {
  [[ ! -e ${deploy_directory} ]] && mkdir -p ${deploy_directory}
  cp index.html build/.
}

** 5 deploy procedure **

Just like slate, execute the following command to finish.

./deploy.sh

Now check out the GitHub Pages project site.
My GitHub Pages that I actually deployed is here.

Reference repository

The repository that tried the two is published below.
https://github.com/Nobuo-Hirai/api-document-use-slate
https://github.com/Nobuo-Hirai/api-document-use-aglio

Impressions of trying the two

Slate was easier because I had experience developing ruby and already had an environment.
Also, slate has more documents and more stars, so I got the impression that slate is safe.

If you have any other good API Document tool, please let us know!