82 lines
3.1 KiB
Markdown
82 lines
3.1 KiB
Markdown
# 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.
|
|
|
|
|
|
|
|
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 <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.
|
|
|
|
|
|
|
|
Go to the directory where you want to clone your repository into and use <br>
|
|
`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
|
|
`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.
|
|
|
|
|
|
|
|
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
|
|
|
|
Text
|
|
|
|
## 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.
|
|
|
|
|
|
|
|
|
|
|