Thanks for contributing to our FlexiHPC User guides repository. Below are ways you can help make the these user guides better.
The easiest way for you to help us is by raising an issue, which will require a GitHub account. For amendments to the documentation, you will need to be familiar with general Git concepts if you'd like to commit substantial changes or even whole new user guides, you will be required to set up the preview environment.
The easiest way to help improve our user guides is by raising an issue in our repository at https://github.com/nesi/flexi-docs.
If you find an issues that needs to be resolved, please have a look through the list of existing issues to see whether your issues hasn't already been reported. If it has, or a closely related issues exists, please add your comments to the existing issue.
If your issue isn't already listed, then create a New Issue. Provide details of your suggestion and include the user guide and url to which your suggestion applies. One of our team members will review your suggestion and resolve it if they can. They may contact you if they need some more clarification.
If you would like to make a minor or substantial contribution, you'll need to ensure you have Git and python installed.
For minor or substantial edits, you will need to clone the repsitory of the documentation source code. This can be done using the Git command:
git clone https://github.com/nesi/flexi-docs.git
You're now ready to make changes.
To contribute substantial edits or new user guides, we recommend that you set up a local development environment, so you can visualise and fine tune your work before you submit it for review.
You'll need some of your git
skills with this.
- Clone the repo to your local computer using
git clone
. - Step through the setup routine (below) to set up your computer for local previews of your edits.
- Make the edits using your favourite markdown editor.
- Commit your changes to your branch.
- Preview your changes using the local preview server that you set up above.
- When you are happy with your edits or additions, commit your changes to the github repo.
- Create a PR from your branch into
main
on the github site
Please be prepared to answer questions about your edits and make additional commits.
Note for windows users, this process will be much easier if you set up Windows Subsystem for Linux (WSL), then the commands below will work within the WSL environment.
Install mkdocs
python3 -m pip install mkdocs
Install theme and addons
pip install mkdocs-material mkdocs-glightbox mkdocs-literate-nav neoteroi-mkdocs
Once the above items are installed you can then serve the files locally with the below command ensuring you are in the root of the cloned repo
mkdocs serve
Then browse to http://localhost:8000/
To commit your work for review you will need to branch from main
and into your own branch.
Using the git
command below and replacing BRANCH_NAME
with a name that is easy to understand.
git branch BRANCH_NAME
Example: git branch 20230815-USER_NAME-Update_Managing_Images
With the code branched and MkDocs running you should be free to alter and create.
All markdown references can be found at the Material for MkDocs reference page.