documentation root folder and links to child pages

[gabriel-vanzandycke]

I'm working on calib3d python GitHub repository
Documentation is generated with

pdoc calib3d -o docs/ -c latex_math=True --force --html

GitHub pages is configured so that documentation points to main branch, docs/ folder, making it available at https://ispgroupucl.github.io/calib3d/

However i have two concerns (probably linked)

1. pdoc builds the documentation inside a subfolder docs/calib3d, making the documentation available in https://ispgroupucl.github.io/calib3d/calib3d instead of expected https://ispgroupucl.github.io/calib3d/. This can be resolved either by
   (a) making a redirect in index.html to calib3d/index.html (current implementation)
   (b) making a symbolic link index.html -> calib3d/index.html (I also tested that one)
2. When using option (a) or (b), I can't have both the links defined in the docstring and the links in the "Sub-modules" section to work. One of the two link is broken (either by missing a calib3d in the url or by having one calib3d too many in the url).

When using the local version pdoc calib3d --http localhost:8000 -c latex_math=True, both links work fine in the browser with both (a) and (b) approaches.

Questions

1. What is the best practice when working with git pages? Where should the documentation be saved (-o option) and how should it be referenced using GitHub pages ?
2. How should the link in the docstring be defined?

Version

pdoc 0.10.0
python 3.8.3

[gabriel-vanzandycke]

**edit note: ** Actually now the two types of link work 🤔 ... But my first question remains: is what I'm doing good practice? What is the best approach to handle the additional subfolder docs/calib3d ?