hattom / easybuild-docs

EasyBuild documentation (mkdocs)

SimpleBuild documentation

This repository contains the sources of the SimpleBuild documentation, which is hosted at https://docs.simplebuild.io.

Format

The documentation sources are located in the docs subdirectory.

They are written in MarkDown format, and rendered using MkDocs, and the Material for MkDocs theme.

Useful links:

• The Markdown Guide: https://www.markdownguide.org
• Reference guide for Material for MkDocs: https://squidfunk.github.io/mkdocs-material/reference

Writing

When writing content for the SimpleBuild documentation, it is useful to get a live preview of how things will look.

Next to the letting mkdocs serve a local copy of the full SimpleBuild documentation so you can view it in your browser (see below), you can also use online services for this. This will allow you to see a live version of standard Markdown, but it will not give you a live preview of the MkDocs specific Markdown extensions.

At https://markdownlivepreview.com you can see a live preview while editing content in MarkDown format.

HackMD (https://hackmd.io) is a MarkDown note service which provides live previewing of the rendered note while you edit in MarkDown format, and collaborative editing of content.

Create a new note via https://hackmd.io/new to preview your content while editing it in MarkDown, and share the note URL with others if you would like to work together on some content.

To save work-in-progress notes and get back to them later, create a dedicated HackMD account, or sign in using your GitHub/Google/... account, via https://hackmd.io/login.

Publishing

The documentation is automatically built and published to https://docs.simplebuild.io on every push to the main branch of this repository.

This is taken care of by the deploy GitHub Actions workflow.

Using mkdocs

Installing mkdocs

To install all the required mkdocs Python packages, use the provided requirements.txt file:

pip install -r requirements.txt

Building

To build the documentation, use:

mkdocs build

or use the Makefile that is provided in this repository:

make

Testing

To test whether the documentation is building correctly, and whether all (internal) links are correct, use:

mkdocs build --strict

or

make test

These commands will exit with a non-zero exit code if mkdocs produces any errors or warnings.

Previewing

To see a local preview of the rendered documentation in your browser, use

mkdocs serve

or

make preview

and click the link that is provided, for example:

INFO     -  Documentation built in 0.24 seconds
INFO     -  [17:52:07] Watching paths for changes: 'docs', 'mkdocs.yml'
INFO     -  [17:52:07] Serving on http://127.0.0.1:8000/

This preview of the rendered documentation will automatically refresh when the documentation sources are updated!

SimpleBuild Framework API

The API documentation for the SimpleBuild Framework is generated automatically if the SimpleBuild framework code is found in src:

mkdir src
cd src
git clone [email protected]:simplebuilders/simplebuild-framework.git

If the SimpleBuild Framework is not found then the mkdocs build of the documentation will be faster, but this will cause a number of warnings messages to be printed.

Contributing

To contribute to the SimpleBuild documentation, you should make a pull request to the main branch.

• Fork the simplebuild-docs repository to your GitHub account, clone the repository and set up a remote for your fork:

  git clone [email protected]:simplebuilders/simplebuild-docs.git
  cd simplebuild-docs
  git add remote YOUR_GITHUB_ACCOUNT [email protected]:YOUR_GITHUB_ACCOUNT/simplebuild-docs.git

• Create a branch for your changes, push it to your fork on the simplebuild-docs repository, and open the pull request:

  vim docs/example.md
  git checkout -b example_branch
  git add docs/example.md
  git commit -m "this is just an example"
  git push YOUR_GITHUB_ACCOUNT example_branch
  # create pull request in GitHub:
  # https://github.com/YOUR_GITHUB_ACCOUNT/simplebuild-docs/pull/new/example_branch