Created workflow docu for repo fork

Reviewed-on: Controls/gitea-pages#3 Co-authored-by: Elke Zimoch <elke.zimoch@psi.ch>
2026-07-02 15:19:51 +02:00
parent 0d76b51cff
commit c3e1ffa3f3
7 changed files with 89 additions and 0 deletions
@@ -0,0 +1,89 @@
+# 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.
+
+
+
+## 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)
+
+
+