boegel / easybuild-docs

EasyBuild documentation

EasyBuild documentation

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

Warning

The sources of the EasyBuild documentation currently still reside at https://github.com/easybuilders/easybuild/tree/main/docs.

We are actively porting the sources from reStructuredText format to MarkDown format.

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

Publishing

The documentation is automatically built and published to https://docs.easybuild.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!

EasyBuild Framework API

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

mkdir src
cd src
git clone [e-mail]:easybuilders/easybuild-framework.git

If the EasyBuild 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 EasyBuild documentation, you should make a pull request to the main branch.

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

  git clone [e-mail]:easybuilders/easybuild-docs.git
  cd easybuild-docs
  git add remote YOUR_GITHUB_ACCOUNT [e-mail]:YOUR_GITHUB_ACCOUNT/easybuild-docs.git

• Create a branch for your changes, push it to your fork on the easybuild-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/easybuild-docs/pull/new/example_branch