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.
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 the build take care of it.
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 (jessitron) will move toward a consistent style and tone after merging.
You can create code snippets in the atomist/samples repo. Demarcate a code snippet using the following comment
// atomist:code-snippet:start=SNIPPET_NAME
CODE HERE
// atomist:code-snippet:end
replacing SNIPPET_NAME
with a unique name for the snippet.
You can then include that snippet in the docs using the following HTML comment in the Markdown source.
<!-- atomist:code-snippet:start=SNIPPET_NAME -->
<!-- atomist:code-snippet:end -->
Then, when either this docs repo or the samples repo is updated, the snippets will be updated in this docs repo.
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.
When a push is made to this repository, the documentation is built by the docs-sdm and published to the S3 bucket docs-sdm.atomist.com under a path starting with the full commit SHA.
If the publication to the docs-sdm bucket is approved, the site is "published" to the docs.atomist.com S3 bucket, making it available at https://docs.atomist.com/.
Before you push changes to this repository, you should test your changes locally.
The project uses MkDocs to generate the static site and htmltest to validate the generated HTML. Below are instructions to install them in a non-obtrusive way.
First install Python 3 using Homebrew on Mac OS X.
$ brew install python3 htmltest
or on Debian-based GNU/Linux distributions
$ sudo apt-get install python3-pip htmltest
Then create a virtual environment to host the dependencies:
$ pip3 install virtualenv
$ mkdir ~/.venvs
$ echo "export PIP_REQUIRE_VIRTUALENV=true" >> ~/.bashrc
$ source ~/.bashrc
$ virtualenv ~/.venvs/docs
With the virtual environment created, activate it in the current terminal:
$ . ~/.venvs/docs/bin/activate
and install the dependencies into it:
$ pip install -r requirements.txt
Every time you want to work on this repository, you need to activate the Python virtualenv in your working terminal:
$ . ~/.venvs/docs/bin/activate
After making changes, you can test them by building the documentation in strict mode.
$ mkdocs build --strict
The run htmltest
.
$ htmltest -c .htmltest.yml site
To review your changes in a browser, you can serve the documentation locally by running:
$ mkdocs serve
and browse the documentation at http://127.0.0.1:8000 . To stop the
server, press Ctrl-C
in the terminal.
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
The activate_and_serve.sh
script activates the virtual environment
and builds, proofs, and serves the docs with a single command.
./activate_and_serve.sh
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.