zimoch_e
c3e1ffa3f3
Reviewed-on: #3 Co-authored-by: Elke Zimoch <elke.zimoch@psi.ch>
3.6 KiB
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.
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.
