This repository contains the sources of the EasyBuild documentation, which is hosted at https://docs.easybuild.io.
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
When writing content for the EasyBuild 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 EasyBuild 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.
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.
To install all the required mkdocs Python packages, use the provided requirements.txt file:
pip install -r requirements.txtTo build the documentation, use:
mkdocs buildor use the Makefile that is provided in this repository:
makeTo test whether the documentation is building correctly, and whether all (internal) links are correct, use:
mkdocs build --strictor
make testThese commands will exit with a non-zero exit code if mkdocs produces any errors or warnings.
To see a local preview of the rendered documentation in your browser, use
mkdocs serveor
make previewand 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!
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 [email protected]:easybuilders/easybuild-framework.gitIf 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.
To contribute to the EasyBuild documentation, you should make a pull request to the main branch.
-
Fork the
easybuild-docsrepository to your GitHub account, clone the repository and set up a remote for your fork:git clone [email protected]:easybuilders/easybuild-docs.git cd easybuild-docs git add remote YOUR_GITHUB_ACCOUNT [email protected]:YOUR_GITHUB_ACCOUNT/easybuild-docs.git
-
Create a branch for your changes, push it to your fork on the
easybuild-docsrepository, 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
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent