Skip to content

Latest commit

 

History

History
99 lines (62 loc) · 3.3 KB

README.md

File metadata and controls

99 lines (62 loc) · 3.3 KB
Raw

Metasys API

The source code for the Metasys Server API documentation hosted by GitHub Pages: https://github.jci.com/pages/g4-metasys-server/api

Quickstart

  1. Clone this repository and checkout the alderaan branch

    git clone [email protected]:g4-metasys-server/api.git
git checkout alderaan

  2. Install all the dependencies

    npm install

  3. Generate a local preview for the documentation. This produces an index.html file which contains a preview of the whole documentation. The preview is generated to build/previews/index.html

    npm run preview

  4. OR generate a preview for an individual section of the documentation. Does the same as above except it only renders the specified section. The preview is generated to build/previews/<group>.html

    npm run preview:group -- --group=spaces

    The extra -- is intentional, that is just how NPM handles parameters

API Blueprint Rendering

The source is currently broken up into individual pages for each part of the API and needs to be combined before publishing to Apiary

Build

Combines all the individual blueprints into a single file inside of the build directory. The built file has the same name as the base index file where the default is index.apib

npm run build

Publish

Publishes the whole built and rendered API blueprint to Apiary. (Only people with access to the Apiary site have permission to publish)

npm run publish

Preview

Renders an HTML file locally to allow viewing of the API documentation before publishing.

npm run preview

Preview Section

This command allows you to preview a single section of the API blueprint. This is useful if you are making changes to a single section and don't want to have to scroll through the whole documenation.

The section specified is one of the directories within the groups directory. The rendered output resides at build/previews/<section>.html

npm run preview:group -- --group=<section>

The extra -- is intentional, that is just how NPM handles parameters

Auto Build

Watches for changes to blueprint files within the api directory and automatically re-renders them.

npm run preview:watch

Contributing

Folder Structure

Each group of actions is housed in a separate file to keep their concerns solely to themselves.

  • groups/ - Contains a collection of groups of actions with each folder representing a separate section
    • <group>.apib - Contains the actions and details regarding the group itself
    • <group>_structs.apib - Contains all the data structures for the specified actions. These are separate since they have to be rendered all together
  • _templates/ - Contains the documentation templates such as the header and introduction sections along with the markdown required to render the data structure section
    • layouts/ - The handlebar templates used for generating the html previews and mono blueprint file

Pull Requests

When a pull request is submitted, TeamCity will automagically generate a full documentation preview which can be shown to reviewers before merging in the changes.

The preview can be accessed via the "API Preview" tab when viewing the build in TeamCity.