Move Repo4Cat documentation to GitHub pages

[vkush]

Prepare wiki-look documentation basing on GitHub-pages, similar as for pid4cat-model (see code here).

[dalito]

...or similar to voc4cat which uses Sphinx with the myst parser to add markdown support. pid4cat uses mkdocs. Do you want to put the documentation into this repo?

If you ask me: I am slightly in favor of sphinx but some find mkdocs easier to work with (the difference is not big). If you can agree to Sphinx and if you find it helpful, I can submit an initial version for the basic structure (as long as I remember the Sphinx special operations we did in voc4cat).

[vkush]

I wanted always to learn Sphinx - so, let's do it via Sphinx ;)
So, if you can, please make the first step with the basic structure basing on voc4cat experience :)

[dalito]

I created an empty gh-pages branch with git checkout --orphan gh-pages, added a 404.html file and a file . nojekyll that is required to host documentation generated with other tools than jekyll. Then I changed the repository settings to use the root of this branch as shown in this screenshot.

[dalito]

The doc-build pipeline fails because I configured it to fail even on warnings. - I submit a fix in a minute.

[dalito]

🚀 Success! https://nfdi4cat.github.io/repo4cat/ - Do you want to keep this issue open until the content is migrated?

This version includes already some notes on how to build the documentation locally.

[vkush]

Let's keep it open until full migration, to have everything in 1 place.

I have a question. Should we use "main" branch also for documentation or an approach with "gh-pages" branch in praxis is better? I read here (this comment), here and the main github-pages documentation.

If we go for the gh-pages branch approach:

1. Should we remove "/docs" folder in the "main" branch? I think - yes.
2. Should we put separate LICENSE file and short README file with the description of license to the "gh-pages" branch (even for the same licence type)? Or text in the "main" README is enough? Not clear for me. I read here and here.
   -> 2.1 This reply is interesting, maybe also good for our case - to write explicitly in LICENSE file (only in "main" branch then?), which parts of code have what licence (even when for our case will be only 1 licence), and on the bottom part of file put the original licence text.
3. Maybe extend README with explicit mention of the gh-branch for the licence issue, like "The content of this repository and its gh-pages (a separate branch "gh-pages")..." or similar? -> maybe depending if we go for 2.1 above or not.

[dalito]

On 1.: The /docs folder in main-branch contains the source (markdown-files and config). This is where you work on.

If a new pull request (with a doc change targeting main) is created and on every later push to the PR branch, a GitHub action is triggered to build the documentation as test if the changes are OK (the created docs are available as build-artefact).

Once a pull request is accepted and the new code merged to main, another GitHub action is triggered to re-build the documentation from the docs-folder in the main branch and to deploy it in the gh-pages branch (see run log).

You never work on the gh-pages branch directly or make it a target of your pull requests. The only exception are very special things like the 404.html that I put there directly.

I think this automation was not considered in the linked discussion. There is also a lot of misinformation/misunderstanding.

On 2.: No. People put the license or README only in the default branch which is main.
On 3.: Since the gh-pages branch is part of the repo it is included in "The content of this repository..." which encloses all branches.