Stretch Docs Generator

This repository generates the documentation hosted at https://docs.hello-robot.com.

The website is generated by aggregating markdown files that are distributed among Stretch's repos. The markdown lives alongside the code it documents, making it easier to keep both in sync. This repo has the role of pulling these repos in as git submodules and integrating them together using the plugin mkdocs-monorepo-plugin.

We use Mkdocs with the Mkdocs Material theme to build the website. Our customization to the default theme can be found in the docs/overrides and docs/extra.css files. Additionally, we use mike for version management. There has been a few versions of Stretch Docs, and visiting https://docs.hello-robot.com automatically redirects to the latest version: 0.3 at the time of this writing. Each version of the docs can be found in a different branch of this repo.

There is a Github Action set up on each submodule included here. Whenever changes to markdown docs merge into mainline in those repos, it automatically trigger a rebuild and deploy of the website here. For a history of deployments, check out the actions tab on Github.

Setup

Follow these steps to get set up with developing on the docs:

git clone https://github.com/hello-robot/hello-robot.github.io
cd hello-robot.github.io
./install.sh

# choose a version of the documentation (details below)
git checkout 0.3
git submodule init
git submodule update

Choose a version

Each version of the documentation is on a separate branch.

/repos/hello-robot.github.io$ git branch
  0.1
  0.2
  0.3
  gh-pages

V0.1 was released with the launch of Stretch RE1. V0.2 was released with the Ubuntu 20.04-based OS upgrade for Stretch robots. V0.3 was released with the launch of Stretch 3.

By using versioning, you can find old docs even as new tutorials and APIs are released. All content is maintained under the version branch. This master branch is mostly empty.

The branch gh-pages is a special orphan branch that the documentation build is pushed to using the Mike versioning plug-in for MkDocs. This branch is hosted via GitHub Pages at https://docs.hello-robot.com,

Previewing Edits

Make edits in the respective repo. For example, if you're updating a tutorial for Stretch Body, edit the markdown file in that repo and open a PR there. Then, pull it here:

cd repos/<repo>
git checkout <pr>

cd ../..
mkdocs serve

You can then preview the content at site http://localhost:8000

Deploying Edits

Note: There's a Github Action set up on most Stretch repos. If a docs change is merged into mainline there, it automatically rebuilds the website and deploys it here. You can check that your change deployed by looking at the actions tab on Github.

If, for example, the version under edit is 0.1, you can push the edits to the webserver by:

cd ~/repos/hello-robot.github.io
mike deploy 0.1 --push

This will push the changes to the gh-pages branch and the edits will be reflected at docs.hello-robot.com.

Note: It may take time / browser refreshes for the changes to be correctly reflected at docs.hello-robot.com,

Making a new version

To make a new version, for example:

cd ~/repos/hello-robot.github.io
git pull
git checkout 0.2
git branch 0.3
git checkout 0.3

<make edits>

mike deploy 0.3 'experimental' -t '0.3: Experimental development' --push

Note the format for the title (-t). Keep a consistent naming structure. Also note that this version is aliased as experimental.

Adding a New Submodule Repo

cd ~/repos/hello-robot.github.io/repos
git submodule add https://github.com/hello-robot/stretch_foo

Updating a Submodule Repo

Start by ensuring your submodules are present:

cd ~/repos/hello-robot.github.io/repos
git submodule init
git submodule update

Once the repos are present you can update them all to the latest commit using:

git submodule update --recursive --remote

Finally, if you want to update the submodules on Github (requires push access), commit the submodules update using:

git add .
git commit -m 'Update all submodules'
git push

Editing a Submodule Repo

For example, Stretch Body:

cd ~/repos/hello-robot.github.io/repos/stretch_body
git pull

Make sure you've pulled the latest version and are on the desired branch. After making your edits you can test them by:

mkdocs serve
...
INFO     -  [21:47:17] Browser connected: http://127.0.0.1:8000/stretch_body/

When the submodule site is as desired, check the changes into Git. Then deploy the edits using Mike:

cd ~/repos/hello-robot.github.io/
mike deploy 0.2 --push
mike serve

Other Tips

The currently hosted versions that are managed by mike can be found with

~/repos/hello-robot.github.io$ mike list
"0.2: Beta (WIP)" (0.2) [beta]
"0.1: Latest" (0.1) [latest]

The default version that is present at is the one with the alias latest as defined in mkdocs.yaml:

extra:
  version:
    provider: mike
    default: latest

To release a version update its alias to latest. Also update its title to accurately reflect this. See the Mike documentation for more information.