aqiank / apidocs

CenturyLink Cloud API Documentation

#CenturyLink Cloud API Documentation

Welcome to the CenturyLink Cloud API Documentation repository. Please follow the guidelines below to contribute or make changes.

If you are new to Git and Github, we highly recommend spending 5 minutes reading this great article on Understanding the Github Flow. This repo follows the Github Flow.

How To Make Contributions

1. Fork the https://github.com/CenturyLinkCloud/APIDocs repository. This will produce a personal copy of this repo.

2. Clone the repo to your desktop.

3. Anything in the master branch is always deployable. Create a new branch from master. Your branch name should be descriptive (e.g., server-power-operations) so that others have an idea of what the branch is for.

4. The master branch represents version 2 of the api, while the v-1 branch is version 1.

5. Once your branch has been created, make your changes (add, edit, delete) your knowledge base article in your favorite Markdown editor (we like Atom).

6. Commit your change(s) locally to your fork/branch.

7. Push or sync your commit(s) to the remote repository on Github.

8. Create a pull request to merge your changes into the master branch.

• Create a pull request using Github for Windows
• Create a pull request using Github for Mac

1. This repository contains a commit analyzer that runs against each file in the repository validating that the following are true:

• File's JSON front-matter parses correctly and contains the required fields (title, date, autor)
• File's markdown successfully parses
• All links and images are valid (doesn't return 404)

Issuing a pull-request will automatically trigger the commit analyzer to validate any changes to the repository as part of continuous integration with travis-ci. If you try to commit changes in which there are syntax errors or broken links, the build log from travis-ci will display which files contain errors, and you will receive an email notification that the build failed.

A pull-request containing errors will look like this:

Any error(s) will be displayed in the Travis-CI build log. The build log is accessible at https://travis-ci.org/CenturyLinkCloud/PublicKB or by clicking on the "Details" link on the pull request page on Github. Here's an example of a broken link:

Pushing/syncing additional commits to your fork/branch will trigger the analyzer to re-check your changes.

A pull-request without errors will also look like this:

Content authors are responsible for making their pull requests pass the commit analyzer. Once they pass, pull requests will be merged.

1. CenturyLink Cloud Team reviews your pull request. If accepted, it will be added to the API Documentation on CenturyLinkCloud.com.

Run the Commit Analyzer locally

If your APIDocs/lib directory is empty, ensure that GitHub ssh is setup correctly, cd to the project root, and run:

git submodule update --init --recursive

To run this check locally, cd into the root of this project and run:

node lib/index.js

Note that the first time you wish to run the commit analyzer, you'll have to run npm install from the lib directory. This assumes you have Node.js installed.

Note: ensure you do not commit any changes to, or auto-prune the APIDocs/lib directory.

Links (API doc to API doc)

Links to other articles should follow this format:

[Link Text](../category/api-doc-name.md)

so like this (folder names are case-sensitive):

[API v2.0 Overview](../Getting Started/api-v2-overview.md)
[Login](../Authentication/login.md )

Commit Analyzer

This repository contains a commit analyzer that runs against each file in the repository validating that the following are true:

• File's JSON front-matter parses correctly and contains the required fields (title, date, autor)
• File's markdown successfully parses
• All relative files (images and other markdown files) are valid links

To run this check locally, cd into the root of this project and run:

node lib/index.js

Note that the first time you wish to run the commit analyzer, you'll have to run npm install from the lib directory. This assumes you have Node.js installed.

The output will tell you if any file fails parsing. This script is also run as part of continuous integration with travis-ci.

TODO: REVERT THIS

Ignoring Files

If a file contains a link that the commit analyzer catches as being invalid (such as in a code sample), and you'd like the analyzer to ignore that file, you can add the filename to commit_analyzer_ignore.txt. (It isn't necessary to include the entire file path; just the filename will suffice.) Each new file should be separated by a new line.