The documentation does not seem to be automatically updated

[Nicogene]

Task description

The mk-docs documentation does not updated

Definition of Done

The GH action keep the documentation updated

[martinaxgloria]

I remembered this issue when I built the page for the first time. This is due to the fact that mkdocs is looking for changes in /docs folder and in mkdocs.yml file:

I've created a file under /docs which is called index.md: it is basically the homepage of ergocub-software documentation and the gh-pages action is looking for it when the site is built.

Trying to point to the README.md, instead, I retrieved an error since it is not in the checked paths. For this reason, to update the documentation, the changes should be done under /doc/mkdocs folder and not directly in the root README.md.

I can open a PR to report the last changes in the right .md files.

cc @Nicogene @pattacini

[martinaxgloria]

Or (maybe better to not have duplicated files) I can change the docs-dir to be the root of the repository. In this way, the homepage can be directly the README.md

[pattacini]

There are multiple ways to do this thing. I have no strong opinions. You may want to look at how documentation is structured.

[martinaxgloria]

I already did, but documentation has a different structure since it has the mkdocs.yml file at the root of the repo, so mkdocs searches for all the .md files starting from the root:

README.md
mkdocs.yml
docs/
   index.md
   ...

In ergocub-software case, instead, there are both mkdocs and doxygen doc generation and, for this purpose, we put both under the same doc folder:

README.md
doc/
  doxygen/
  mkdocs/
    mkdocs.yml
    docs/
        index.md
        ...

The nav configuration is defined from mkdocs.yml on, so the root README.md is not found.

Maybe we can wait for @Nicogene opinion and decide how to proceed.

cc @pattacini

[Nicogene]

I would move the mkdocs.yml in the root of the repo and remove the copy of the README under the docs folder, otherwise the github action should copy the changes made in the README.md to the docs/index.md

[martinaxgloria]

Moving mkdocs.yml at the root of the repo means that some changes should be done also in the workflow of gh-pages deployment. What about adding docs-dir parameter in the mkdocs.yml file and setting it to be the root? In this way, nothing should be modified in the gh action and every time it is triggered, mkdocs will search for changes in the whole repository.

cc @Nicogene

[Nicogene]

What about adding docs-dir parameter in the mkdocs.yml file and setting it to be the root? In this way, nothing should be modified in the gh action and every time it is triggered, mkdocs will search for changes in the whole repository.

Ok for me!