Skip to content

First time setup

This document contains the step-by-step guide to setup the documentation branch and the corresponding automations for a new repository.

1. Create the documentation branch

If you are starting from a new a repository, run the following commands to initialize the directory structure. The Github-based automation requires that the documentation is on its own branch named docs-develop. Here we'll find the most up-to-date documentation for the project.

Move inside the desired repository and create an orphan branch (note: switch requires git 2.23):

git switch --orphan docs-develop

git push --set-upstream origin docs-develop
Cleanup the branch

You might need to cleanup the untracked files inside the folder before moving on:

git rm -rf . && rm .gitignore

2. Copy the project files from the template repository

Simply copy the project files from the template repository at https://github.com/eurotech/docs-guide. You should have the following resulting directory structure:

.
├── .gitignore
├── .github
│   └── workflows
│       ├── backport.yml
│       ├── build-deploy-docs.yml
│       └── pr-lint.yml
├── README.md
├── docs
│   ├── assets
│   │   ├── eurotech_logo.svg
│   │   └── favicon.svg
│   ├── index.md
│   └── stylesheets
│       └── extra.css
├── mkdocs.yml
└── requirements.txt

3. Setup the environment

The complete installation instruction are available in the documentation but we'll report them here for convenience.

Requirements:

Install the requirements with:

pip3 install --upgrade pip

pip3 install -r requirements.txt
Virtual Environment

It is recommended to create a Python virtual environment for this. See the installation instructions for details.

4. Customize the documentation for your project

Be sure to update the mkdocs.yml and docs/*.md files with the correct information for your project repository.

Tip

The parameters to be changes inside the mkdocs.yml file are clearly labeled by CHANGEME comments.

You can check that everything looks good by building the website with the command (see Usage section):

mkdocs serve

Once everything looks good commit and push your changes.

This will kick in the Github automation which will build you documentation. You won't be able to see your docs yet though because we still need to setup the version to serve by default.

5. Version configuration

Warning

For the following steps you'll need write permissions on the repository.

After the Github automation completes the build you should see that the gh-pages branch was created. Pull the latest changes on your local repo before moving on:

git pull

Now we will setup the development documentation as the latest documentation.

mike alias docs-develop latest --update-aliases --push

Finally we'll serve the latest documentation by default

mike set-default --push latest
Updating aliases

Once you'll have a new release you'll need to update which version to serve. This is simply done by issuing: 

mike alias docs-release-[version] latest --update-aliases --push
Where the docs-release-[version] is the name of the branch where the documentation for that release resides.

Troubleshooting

Can't see the documentation on Github pages

If even after setting the docs-develop branch as the default documentation branch you still can't see the documentation, you might need to update the Github repository settings.

Go to your Github repository page's Settings -> Pages, under "Build and deployment" ensure your settings looks like the following:

Build and deployment settings