Writing Controls Documentation

Different Types of Docu

The Grand Unified Theoriy of Documentation

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.

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/

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.

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.

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
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.

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

Now you can work in this directory and write the documentation you intended. All the markdown files are located in the docsdirectory 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.

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
https://<your_username>.pages.psi.ch/<your_fork_name>/

For example my fork from the examples above is reachable with
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.

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

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

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

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
git fetch upstream master
git reset --hard upstream/master
git push --force origin master

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.