More robust setup with `mkdocs`

[etiennebacher]

mkdocs is problematic because we need to run mkdocs build at some point to finalize the construction of the docs folder. However, mkdocs can be installed in various locations, such as a .venv folder in the package directory or somewhere else in the computer. We can't reasonably guess what is the right location so we need some user interaction at some point.

One option would be to force the user to setup a .venv directory in their package directory and tell them to install mkdocs there before running render_docs(). At the end of render_docs(), I suppose we could run bash -c 'source .venv/bin/activate && mkdocs build' (need to try that).

Related comment in polars PR: https://github.com/pola-rs/r-polars/pull/540#issuecomment-1849116134

cc @eitsupi if you want to participate (but you don't have to ofc)

[eitsupi]

Considering that .venv is a commonly used folder, I doubt if forcing it to venv is a good idea.

Perhaps the recommended practice in the Python world is to have it installed mkdocs material via pipx and the command is on the PATH. (Not confirmed)

[etiennebacher]

I've made progress on that in #213. Here's what happens when the user runs setup_docs("mkdocs"):

• error if the folder .venv_altdoc doesn't exist
• show instructions on how to create it, activate it, and install mkdocs
• setup_docs("mkdocs") + render_docs() should now work

At the end of render_docs(), we run a bash/shell command (depending on the OS) that activates the venv and runs mkdocs build (see https://github.com/etiennebacher/altdoc/pull/213/files#diff-baec95f4b43c23e1e322957f4eabcd7ad4a153da61f952557429dd14aa23994e).

It would be great if I could have feedback on this. Note that the PR in r-polars (https://github.com/pola-rs/r-polars/pull/540) works with this setup.

[eitsupi]

If you want to automatically create folders, I recommend that you also update gitignore and Rbuildignore. In particular, if you do not update gitignore, tens of thousands of files may suddenly appear as differences, which may put a burden on the development environment.

[etiennebacher]

Thanks, I forgot about this, it's fixed