Open `http://127.0.0.1:8000` with a web browser to preview the local copy of the documentation.
#### Build Static Documentation
To build the documentation, invoke `mkdocs build`. This will create a new directory named `public`
which holds the generated static html/jss/css files. This command is used to build the documentation
within the CI/CD pipeline. Thus, it should exit without error.
```Shell Session
~ cd /PATH/TO/hpc-compendium/doc.zih.tu-dresden.de
~ mkdocs build
INFO - Cleaning site directory
INFO - Building documentation to directory: /PATH/to/hpc-compendium.git/doc.zih.tu-dresden.de/public
INFO - Documentation built in 0.09 seconds
```
## Git Workflow
todo
It's important to keep your main branch in sync with upstream when you are working on documentation locally. To get started you will need to do the following:
Add a remote upstream to point to upstream repository
Checkout main and sync main branch locally from upstream endpoint
git checkout main
git pull upstream main
To push your sync changes to your fork you can do the following:
git push origin main
!!! note Please don't use your main branch to make any changes, this branch is used to sync changes from upstream because all merge requests get pushed to main branch. Instead, create a feature branch from main as follows:
Typical workflow
The user workflow can be described in the following steps assuming you are using upstream repo. Please make sure you sync your main branch prior to creating a branch from main.
git checkout main
git checkout -b <BRANCH>
git add <file1><file2>
git commit -m <COMMITMESSAGE>
git push origin <BRANCH>
Next create a merge request to the main branch with your newly created branch. Please make sure the markdownlint check and continuous integration checks have passed for your merge request.
* It is possible the GitLab shared runners will fail for an opaque
reason (e.g. issues with the cloud provider where they are hosted).
Hitting the **Retry** button may resolve this problem.
##
If you are totally sure about your commit (e.g., fix a typo), it is only the following steps:
## Content Rules
1. Synchronize branches
1. Edit the markdown file of interest
1. Commit change
1. Push commit to your fork and probaly new branch
1. Pose Merge Request
### Checks
Several checks are invoked to ensure for a consistent and high quality documentation:
* Markdown linter
* Links
* Code and command examples
TODO: Describe
### Markdown
todo
### Markdown Linter
...
...
@@ -71,6 +261,34 @@ ERROR: 1 dead links found!
[✖] google.de → Status: 400
```
## Content Rules
### Add a New Page
All `mkdocs` project follow this structure:
```Bash
mkdocs.yml # The configuration file.
docs/
index.md # The documentation homepage.
... # Other markdown pages, images and other files.
```
To add a new page to the documentation follow these two steps:
1. Create new markdown file under `docs/SUBDIR/NEW.md` and put the documentation inside
1. Add `SUBDIR/NEW.md` to the configuration file `mkdocs.yml` by updating the navigation section
Make sure that the new page is not floating, i.e., it can be reached directly from the documentation
structure.
### Markdown
TODO: What dialect we are using?
### Writing Style
### Spelling and Technical Wording
...
...
@@ -109,3 +327,11 @@ drwxr-xr-x 3 zwulf p_zwulf 4096 Feb 12 2020 data
### Code Blocks
All code blocks should be runnable from a login node.
