Set Up and Work Locally¶
One of the mechanisms to work with the documentation is to run it on your computer using Docker. This allows you to work offline and see the documentation rendered in a web browser.
Prerequisites¶
Fork Repository¶
Fork the e-INFRA CZ documentation repository. This will create your own clone of upstream e-INFRA CZ documentation repository where you will be able to make changes. Once you are happy with your changes, use GitLab to submit them to our original repository.
Clone Repository¶
# after creating your own copy of the repository on GitLab
git clone git@gitlab.ics.muni.cz:einfra-docs/documentation.git
Create New Branch¶
At the moment there is no convention on how to name the feature branches. Try to make clear what feature will be added within the new branch.
# in `documentation` folder
git checkout -b my_change
Make Changes & Run Local Server¶
You can edit the documentation and run local server to see changes live. Use our start.sh, which will use our production Docker container and will create production version server of the documentation locally on your PC. Then go to http://localhost:8080 to see changes, from now, every change will reload the page in the browser automatically.
./start.sh
By default the URL where the server listens is http://localhost:8080
Note
Edits will be shown live in your browser window, no need to restart the server.
Partial Documentation Building¶
If you don't want to build the whole documentation (due to its big build time), you can choose to build only subset of the whole documentation site by using argument -f <path to mkdocs.yml of subdocumentation>
./start.sh -f topics/about-us/mkdocs.yml
Publishing Changes¶
Now you are ready to send changes to your forked repository of the e-INFRA CZ documentation.
Commit and Push Changes¶
If you are satisfied with your changes and you did build the whole documentation to review you changes in the context of the whole site commit and push changes to main repository:
git commit -am "Commit message"
git push --set-upstream origin my_change
Submit Changes¶
Create a Merge Request via GitLab @ ICS MU to send your changes to upstream repository. Please refer to the tutorial on how to create merge request to upstream repository at Gitlab documentation.