JayeX - Cloud Native CI/CD Built On Kubernetes

Suggest changes to documentation

Mon, 01 Jan 0001 00:00:00 +0000

Did you spot a typo or feel something’s missing from a certain page? You can still contribute your suggestions without having to go through setting everything up locally as explained on Contribute to Documentation.

The process requires only three steps:

Click the “Edit this page” link on the right
Make your suggested changes
Create a Pull Request

We’ll go through each step here. Keep in mind though, that if you’re looking to contribute larger amounts of changes, pages, or sections, it’s best to test things out locally first (using the process described on Contribute to Documentation) instead of using this method.

API Documentation

Mon, 01 Jan 0001 00:00:00 +0000

JayeX has two types of API documentation: Kubernetes Custom Resource Documentation and Godoc. Both types are generated from the codegen binary which is part of the jx repository.

Setup your development environment

It’s best to make changes to the JayeX code on your local machine. Follow the development guide to get set up.

Writing custom resource documentation

The custom resource documentation is mostly generated from the comments on the go structs that define the custom resources, with the introductory content and structure injected.

Step by Step setup

Mon, 01 Jan 0001 00:00:00 +0000

We’ll go through each step below, but here’s what you need to get started with Git:

The git command line interface installed locally
a GitHub account
a local working copy of the code

Install Git on your system

Git is a version control system to track the changes of source code.

You will need to have Git installed on your computer to contribute to JayeX development. Teaching Git is outside the scope of the JayeX docs, but if you’re looking for an excellent reference to learn the basics of Git, we recommend the Git book if you are not sure where to begin.

Documentation Style Guide

Mon, 01 Jan 0001 00:00:00 +0000

Documentation writer style guide

The JayeX Documentation Special Interest Group (SIG) has established some guidelines for docs contribution. The following are not meant to be exhaustive, but are simple style and technical tips to help conform to the existing voice and technical writing techniques used in our existing docs content.

Writer voice and tone

Pages should have titles, and should be descriptive enough on its own that readers (and web search crawlers) can pick up the title without too much missing context. Proper nouns should be capitalized in titles but nothing else (for example, write “JayeX tips and tricks” instead of “JayeX Tips And Tricks”)

References

Mon, 01 Jan 0001 00:00:00 +0000

The following sections contains other information that’s helpful when working with Hugo and the JayeX site; you don’t necessary need to go through this if this is your first time.

Search by Algolia/DocSearch

We’re using DocSearch by Algolia to power the internal search.

The script and local config are declared in /layouts/partials/scripts.html
Styling is included via /layouts/partials/head-css.html
The configuration is managed in the Algolia console.

Markdown Syntax Reference

Code examples

Hugo uses goldmark parser to handle markdown and markdown related configuration and chroma to handle syntax highlighting. Chroma supports the following languages. All pages on the JayeX docs use the typical triple-back-tick markdown syntax.

Contribution workflow

Mon, 01 Jan 0001 00:00:00 +0000

Once you’ve completed the initial steps to get started, you can begin to make changes and add new content.

At a high level, your workflow will likely look something like this:

Create a new branch for you work
Start the Hugo server to preview your changes (updates the site live)
Make changes/add new content
Commit and push your changes to your fork of jx-docs
Raise a Pull Request (PR) to have your changes merged into the main jx-docs repo
Wait for and then participate in a review of your changes
- might involve making adjustments or adding a bit more
See your changes go live on the JayeX site

We’ll go though each of the steps below in more detail