diff --git a/docs/5._Controls_Internal/Workflows/images/ActionsSetting.png b/docs/5._Controls_Internal/Workflows/images/ActionsSetting.png new file mode 100755 index 0000000..3f47bac Binary files /dev/null and b/docs/5._Controls_Internal/Workflows/images/ActionsSetting.png differ diff --git a/docs/5._Controls_Internal/Workflows/images/giteaFork_1.png b/docs/5._Controls_Internal/Workflows/images/giteaFork_1.png new file mode 100755 index 0000000..7567448 Binary files /dev/null and b/docs/5._Controls_Internal/Workflows/images/giteaFork_1.png differ diff --git a/docs/5._Controls_Internal/Workflows/images/giteaFork_2.png b/docs/5._Controls_Internal/Workflows/images/giteaFork_2.png new file mode 100755 index 0000000..b128659 Binary files /dev/null and b/docs/5._Controls_Internal/Workflows/images/giteaFork_2.png differ diff --git a/docs/5._Controls_Internal/Workflows/images/giteaFork_3.png b/docs/5._Controls_Internal/Workflows/images/giteaFork_3.png new file mode 100755 index 0000000..97692f1 Binary files /dev/null and b/docs/5._Controls_Internal/Workflows/images/giteaFork_3.png differ diff --git a/docs/5._Controls_Internal/Workflows/images/giteaFork_4.png b/docs/5._Controls_Internal/Workflows/images/giteaFork_4.png new file mode 100755 index 0000000..b730ae9 Binary files /dev/null and b/docs/5._Controls_Internal/Workflows/images/giteaFork_4.png differ diff --git a/docs/5._Controls_Internal/Workflows/images/giteaPush.png b/docs/5._Controls_Internal/Workflows/images/giteaPush.png new file mode 100755 index 0000000..7d978ec Binary files /dev/null and b/docs/5._Controls_Internal/Workflows/images/giteaPush.png differ diff --git a/docs/5._Controls_Internal/Workflows/writeDocu.md b/docs/5._Controls_Internal/Workflows/writeDocu.md new file mode 100644 index 0000000..8f83191 --- /dev/null +++ b/docs/5._Controls_Internal/Workflows/writeDocu.md @@ -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//` + +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. + +![Where to look up the url](images/giteaFork_3.png) + +Go to the directory where you want to clone your repository into and use
+`git clone ` + +![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
+`https://.pages.psi.ch//` + +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. + +![Enable Actions for your gitea repository](images/ActionsSetting.png) + + +