design/api/README.md
author ymh <ymh.work@gmail.com>
Wed, 05 Dec 2018 19:00:08 +0100
changeset 193 99e342f9fb0c
parent 116 672e3c4bbd0c
permissions -rw-r--r--
Display protocol graphically
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
116
672e3c4bbd0c add documentation for metacategory editor
ymh <ymh.work@gmail.com>
parents:
diff changeset
     1
# Generation of API documentation
672e3c4bbd0c add documentation for metacategory editor
ymh <ymh.work@gmail.com>
parents:
diff changeset
     2
672e3c4bbd0c add documentation for metacategory editor
ymh <ymh.work@gmail.com>
parents:
diff changeset
     3
The documentation use the api blueprint format ([documentation](https://apiblueprint.org)).
672e3c4bbd0c add documentation for metacategory editor
ymh <ymh.work@gmail.com>
parents:
diff changeset
     4
672e3c4bbd0c add documentation for metacategory editor
ymh <ymh.work@gmail.com>
parents:
diff changeset
     5
[Aglio](https://github.com/danielgtaylor/aglio) is used for rendering the documentation into html.
672e3c4bbd0c add documentation for metacategory editor
ymh <ymh.work@gmail.com>
parents:
diff changeset
     6
672e3c4bbd0c add documentation for metacategory editor
ymh <ymh.work@gmail.com>
parents:
diff changeset
     7
## install Aglio
672e3c4bbd0c add documentation for metacategory editor
ymh <ymh.work@gmail.com>
parents:
diff changeset
     8
672e3c4bbd0c add documentation for metacategory editor
ymh <ymh.work@gmail.com>
parents:
diff changeset
     9
```bash
672e3c4bbd0c add documentation for metacategory editor
ymh <ymh.work@gmail.com>
parents:
diff changeset
    10
$ npm install
672e3c4bbd0c add documentation for metacategory editor
ymh <ymh.work@gmail.com>
parents:
diff changeset
    11
```
672e3c4bbd0c add documentation for metacategory editor
ymh <ymh.work@gmail.com>
parents:
diff changeset
    12
672e3c4bbd0c add documentation for metacategory editor
ymh <ymh.work@gmail.com>
parents:
diff changeset
    13
### Available commands
672e3c4bbd0c add documentation for metacategory editor
ymh <ymh.work@gmail.com>
parents:
diff changeset
    14
672e3c4bbd0c add documentation for metacategory editor
ymh <ymh.work@gmail.com>
parents:
diff changeset
    15
- Build the documentation (file metacategory.html)
672e3c4bbd0c add documentation for metacategory editor
ymh <ymh.work@gmail.com>
parents:
diff changeset
    16
```bash
672e3c4bbd0c add documentation for metacategory editor
ymh <ymh.work@gmail.com>
parents:
diff changeset
    17
$ npm run build
672e3c4bbd0c add documentation for metacategory editor
ymh <ymh.work@gmail.com>
parents:
diff changeset
    18
```
672e3c4bbd0c add documentation for metacategory editor
ymh <ymh.work@gmail.com>
parents:
diff changeset
    19
672e3c4bbd0c add documentation for metacategory editor
ymh <ymh.work@gmail.com>
parents:
diff changeset
    20
This runs the following command:
672e3c4bbd0c add documentation for metacategory editor
ymh <ymh.work@gmail.com>
parents:
diff changeset
    21
```bash
672e3c4bbd0c add documentation for metacategory editor
ymh <ymh.work@gmail.com>
parents:
diff changeset
    22
$ aglio -i metacategory.apib -o metacategory.html
672e3c4bbd0c add documentation for metacategory editor
ymh <ymh.work@gmail.com>
parents:
diff changeset
    23
```
672e3c4bbd0c add documentation for metacategory editor
ymh <ymh.work@gmail.com>
parents:
diff changeset
    24
672e3c4bbd0c add documentation for metacategory editor
ymh <ymh.work@gmail.com>
parents:
diff changeset
    25
- Watch the documentation.
672e3c4bbd0c add documentation for metacategory editor
ymh <ymh.work@gmail.com>
parents:
diff changeset
    26
```bash
672e3c4bbd0c add documentation for metacategory editor
ymh <ymh.work@gmail.com>
parents:
diff changeset
    27
$ npm run watch
672e3c4bbd0c add documentation for metacategory editor
ymh <ymh.work@gmail.com>
parents:
diff changeset
    28
```
672e3c4bbd0c add documentation for metacategory editor
ymh <ymh.work@gmail.com>
parents:
diff changeset
    29
672e3c4bbd0c add documentation for metacategory editor
ymh <ymh.work@gmail.com>
parents:
diff changeset
    30
This runs the following command:
672e3c4bbd0c add documentation for metacategory editor
ymh <ymh.work@gmail.com>
parents:
diff changeset
    31
```bash
672e3c4bbd0c add documentation for metacategory editor
ymh <ymh.work@gmail.com>
parents:
diff changeset
    32
aglio -i metacategory.apib -s
672e3c4bbd0c add documentation for metacategory editor
ymh <ymh.work@gmail.com>
parents:
diff changeset
    33
```
672e3c4bbd0c add documentation for metacategory editor
ymh <ymh.work@gmail.com>
parents:
diff changeset
    34
672e3c4bbd0c add documentation for metacategory editor
ymh <ymh.work@gmail.com>
parents:
diff changeset
    35