Atomist documentation

This repository contains the markdown sources for the documentation for Atomist. You can find the current version of the Atomist documentation at https://docs.atomist.com/.

The documentation is generated from markdown using MkDocs.

Editing

Much of the documentation is hand-generated, so you can feel free to edit.

We use the Google Developer Documentation Style Guide as our guide and suggest the Style guide highlights for a summary.

See below for instructions on how to test your changes locally.

You are not required to test your changes locally in order to contribute. Edit right on GitHub, and let Atomist (our build automation) take care of it.

Contribution criteria

Pull requests will be merged if they are better than the existing text. They don't need to be perfect.

Here's how I define better:

Out-of-date information is the worst.
Emptiness is better than inaccurate information.
Any (accurate) information is better than none.

Additional links and information are great.

We will move toward a consistent style and tone after merging.

Build and serve the documentation locally

Before you push changes to this repository, you may test your changes locally.

Instant Development environment

Docker

You can build the docs with the following command.

$ docker run -it --rm -v "$PWD:/docs" squidfunk/mkdocs-material:5.3.3 build --strict

You can also run htmltest.

$ docker run -it --rm -v "$PWD:/test" wjdp/htmltest:v0.12.0 htmltest

You can serve the docs with the following command.

$ docker run --rm -it -p 8000:8000 -v ${PWD}:/docs squidfunk/mkdocs-material:5.3.3

VS Code

If you open this repository in VSCode, and you have Docker, and you have the VSCode extension for remote containers, then VSCode will offer to open the folder in a container. Accept that, and you'll have a development environment with the right tools installed.

In the terminal inside VSCode, you can type

serve and then access your local, hot-reloading version of these docs on localhost:8000.

build will build the site and test the links.

You may now skip the rest of this section. Continue with [including code snippets from other repos][code-snippets]

macOS

Initial setup (and re-setup every time python gets updated).

$ rm -rf ~/.venvs/docs
$ mkdir -p !$
$ PIP_REQUIRE_VIRTUALENV=false pip3 install virtualenv
$ virtualenv ~/.venvs/docs

Initial install of htmltest.

$ tar -x -z -f htmltest_0.13.0_osx_amd64.tar.gz
$ install htmltest /usr/local/bin

Initialize virtualenv in your shell and install dependencies.

$ . ~/.venvs/docs/bin/activate
$ pip3 install -r requirements.txt

Actually build and serve the site.

$ mkdocs build --strict
$ htmltest
$ mkdocs serve

You can then access the local site at http://127.0.0.1:8000/ .

Styles

We use the Admonition extension to mkdocs. Here are the available admonition styles:

summary tldr
hint important tip
check done success
attention caution warning
fail failure missing
danger error
bug
default (i.e., none of the above)

Items on the same line create a visually equivalent admonition.

Buiding and Releasing

When a push is made to this repository, the documentation is built to https://docs.atomist.services using a CloudBuild trigger. The cloud build steps are in this cloudbuild.yaml file. In the atomist-web-docs-staging project, the cloudbuild service account has been given permission to deploy content updates to firebase. See instructions here.

When this repo is tagged, the documention is built to https://docs.atomist.com using a CloudBuild trigger. The steps for the cloud build are in this cloudbuild-prod.yaml.

Updating dependencies

The requirements.txt file sets specific versions for the packages. To update to new versions, you can use the following command:

$ ( cut -d = -f 1 requirements.txt > req.txt && \
      cat req.txt | xargs -n 1 pip install -U && \
      pip freeze -r req.txt > requirements.txt ) ; \
    rm req.txt

To update html-proofer and its dependencies:

$ bundle update

Conditions of use

This documentation build process is provided to the public purely for the purpose of testing documentation changes before submitting pull requests to the appropriate Atomist repository.

The documents produced by this build process may be published only on https://docs.atomist.com/. They may not be published in any other form or on any other website without explicit permission.

Created by Atomist. Need Help? Join our Slack workspace.

atomisthq/docs