forked from Controls/gitea-pages
zimoch_e
4a0a6fe152
Build and Deploy Documentation / build-and-deploy (push) Successful in 6s
Reviewed-on: Controls/gitea-pages#4 Co-authored-by: Elke Zimoch <elke.zimoch@psi.ch>
121 lines
5.0 KiB
Markdown
121 lines
5.0 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 <br>
|
|
[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.
|
|
|
|
|
|
|
|
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.
|
|
|
|
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 <br>
|
|
`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 <br>
|
|
`git fetch upstream master` <br>
|
|
`git reset --hard upstream/master` <br>
|
|
`git push --force origin master` <br>
|
|
|
|
|
|
## 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.
|
|
|
|
|
|
|
|
|
|
|