# Writing Controls Documentation

## Different Types of Docu

[The Grand Unified Theoriy of Documentation](https://docs.divio.com/documentation-system/)

## How to publish Controls Docu

Everything is automated. The changes are rendered as soon as you push to the gitea 
repository [https://gitea.psi.ch/Controls/gitea-pages](https://gitea.psi.ch/Controls/gitea-pages).

The webpage is generated from markdown files using Zensical together with Gitea Actions. 
The process to setup such page is described here 
[https://linux.psi.ch/documentation/services/gitea/gitea-pages/](https://linux.psi.ch/documentation/services/gitea/gitea-pages/)

## How to work with your own fork

If several people work at the same time on the same repository  but on different files,
it can help to create your own fork in your own gitea name space. This will make it 
easier to debug zensical rendering errors and layout changes without disturbing
colleagues.

### Fork into your name space

First you have to fork the repository by clicking on the Fork button in the upper right corner.

![Fork Button on Gitea page](images/giteaFork_1.png)

Gitea will then prompt you to put in some information in a popup window. It is suggested to change the repository name, so that
you will not overwrite any existing repository for webpages in your own namespage. In the expample I used ez_dpli_test as a
name. And I provided some description for some future reference.

![Rename you directory](images/giteaFork_2.png)

Gitea now opens a browser view of your new fork repository. Otherwise you can find it in giteain your namespace with the 
name you selected in the step before:
`https://gitea.psi.ch/<your_username>/<your_fork_name>`

In the expampe that would be <br>
`https://gitea.psi.ch/zimoch_e/ez_doku_test`


### Clone your name space version

Lookup the ssh url to clone your repository by clicking on the Code button and copy the displayed address.

![Where to look up the url](images/giteaFork_3.png)

Go to the directory where you want to clone your repository into and use <br>
`git clone <your_repository_url>`

![Command line to clone your forked directory](images/giteaFork_4.png)

Now you can work in this directory and write the documentation you intended. All the markdown files are located in the
`docs`directory where the structure of the webpage is created.

### Review your local changes

Once you wrote the documentation, you add, committ, and push to your forked repository.

![Push your changes to your forked repo](images/giteaPush.png)

It might take some seconds until your pages is renedered. I have seen times up to 15 seconds.

Your forked webpages can be found in the directory <br>
`https://<your_username>.pages.psi.ch/<your_fork_name>/` 

For example my fork from the examples above is reachable with <br>
`https://zimoch_e.pages.psi.ch/ez_doku_test/` 

### Merge into main Controls Documentation

Once you have done all the intended changes to your forked repository, you have to merge it back into the main controls pages.
The following workflow assumes that you needed to commit several changes until you were satisfied with the result, but all
changes were mostly cosmetically (e.g. typos, better rendering, inserting subtitles, etc.).

First you make sure that all changes are pushed to your forked repository.

Now you should have a button on the webinterface that will create a *New Pull Request*. Otherwise you can 
initiate a pull request from the original repository `Controls/gitea-pages` by changing into the
*Pull Request* tab.

![Create a pull request from your forked repository](images/giteaFork_5.png)

In the following window you should add a one-line comment that summarizes you commit messages.
Afterwards you create the pull request.

![Comment on the pull request](images/giteaFork_6.png)

Now you can see your pull request in the tab of the original repository `Controls/gitea-pages`. 

![Pull request tab](images/giteaFork_7.png)

To accept the pull request (not all people might have the rights to do so), click on the listed item
and select <br>
`Create squash commit`

![Create squash commit](images/giteaFork_8.png)

This will squash all commits you did on the fork into just one commit in the master branch. It
is requested to do so in case all your commits were creating just one documentation page and committed
several times to save intermedite results or correct typos and wrong formatting.

After your changes were merged into the master branch you can either delete your forked repository
and checked out directory (be very sure that you delete the inteded stuff!) or you can later
reuse your fork for creating another documentation. In the second case use the commands <br>
`git fetch upstream master` <br>
`git reset --hard upstream/master` <br>
`git push --force origin master` <br>


## Debugging Problems

When severe errors in the markdown files hinder the redering, you can see the error messages in the Actions tab of 
the gitea repository. For your local fork you might need to enable it in the settings of the repository.

![Enable Actions for your gitea repository](images/ActionsSetting.png)