Skip to content

Latest commit

 

History

History
252 lines (171 loc) · 6.45 KB

README.md

File metadata and controls

252 lines (171 loc) · 6.45 KB
Raw

New Project

This repository contains the markdown sources for the documentation for Something. You can find the current version of the Something documentation at https://atomist-seeds.github.io/mkdocs-site.

The documentation is generated from markdown using MkDocs.

Editing

Much of the documentation is hand-generated, so you can feel free to edit. We try to adhere to the Google Developer Documentation Style Guide. See [below][build-serve] 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.

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.
  • Placeholders are better than emptiness.
  • Any (accurate) information is better than none.

Additional links and information is great.

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

Content reuse

Sometimes it's desirable to have certain content repeated in a page or duplicated across pages. This project uses a markdown-include plugin to include content from files in the docs/common directory prior to conversion to HTML. It uses the {!filename!} syntax, with all filenames relative to the docs/common directory.

e.g. to include the content from docs/common/handlers.md into user-guide/rug/commands.md, we simply add {!handlers.md!} to the desired location in user-guide/rug/commands.md.

Styles

We use the Admonition extension. 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.

Build and serve the documentation locally

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

Install dependencies

The project uses MkDocs to generate the static site and HTMLProofer to validate the generated HTML. Below are instructions to install them in a non-obtrusive way.

MkDocs

First install Python 3 using Homebrew on Mac OS X.

$ brew install python3

or on GNU/Linux

$ sudo apt-get install python3.6
$ curl -O https://bootstrap.pypa.io/get-pip.py
$ sudo python3.6 get-pip.py

Then create a virtual environment to host the dependencies:

$ pip3 install virtualenv
$ mkdir ~/.venvs
$ echo "export PIP_REQUIRE_VIRTUALENV=true" >> ~/.bashrc
$ source ~/.bashrc
$ virtualenv -p python3.6 ~/.venvs/userdocs

With the virtual environment created, activate it in the current terminal:

$ . ~/.venvs/userdocs/bin/activate

and install the dependencies into it:

$ pip install -r requirements.txt

HTMLProofer

Install HTMLProofer using rbenv. First install rbenv.

$ brew install rbenv
$ eval "$(rbenv init -)"

Install a recent version of Ruby using rbenv and then set that as the version to be used in this project.

$ rbenv install 2.4.1
$ rbenv local 2.4.1

Install the bundler gem.

$ gem install bundler

Finally, install HTMLProofer.

$ bundle install

Testing and serving

Every time you want to work on this repository, you need to activate the Python virtualenv in your working terminal:

$ . ~/.venvs/userdocs/bin/activate

After making changes, you can test them by building the documentation in strict mode and running HTMLProofer on the resulting site.

$ mkdocs build --strict && ./htmlproof.sh

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.

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

Shortcut

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

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.

Created by Atomist.