Code42 Developer Portal

To build the site locally, you will need the following:

• Ruby >= 2.4.1 and < 3.0
• homebrew (if using macOS)
• jq <= 1.6
• wget
• api-spec-converter
• MarkdownTools2

Installing dependencies

We are using Slate to build the documentation, so the dependencies for build can be installed by following their documentation. It is reproduced here with the additional steps needed for our other dependencies.

setup_artifactory_auth_npm
gem install bundler:2.1.4
bundle install
npm install api-spec-converter

Bundler documentation is handy if you run into issues: Bundler troubleshooting page

Slate documentation if the above is not successful:

• Installing Dependencies on Ubuntu 18.04+
• Installing dependencies on macOS

Note that Slate is unsupported on Windows.

User Guides

The user guides are separated into their own files for easy navigation and editing. The MarkdownTools2 package provides the CLI command mdmerge that we use to merge these files into one so that they can be hosted on a single page.

You can install MarkdownTools2 with pip:

pip install MarkdownTools2

Use the following command to build the source/api/user_guides.rmd file.

make docs

To add a user guide:

1. add it to the source/api/user-guides directory.
2. insert it into the proper index within the make docs command. (This is the order that the markdown files will be merged.)
3. rebuild the docs via make docs.

Build

To build, execute:

make

Once built, the site can be run locally using middleman, which is included when installing.

make serve

Then, open your browser to localhost:4567 to explore the site. Once the server is started, you can edit files and simply refresh the page to see your changes!

Development with a local Baldur instance

The dev portal can build docs from a locally running Baldur instance by modifying the DOCS_SERVER variable in the Makefile to the url of your local Baldur. By default, that is http://localhost:5000