Why the requirement for mkdocs to be installed?

[nsheff]

First: Thanks for this excellent work, I'm very excited to be using altdoc for documenting several of my R packages. I am most excited about it because of the mkdocs output target, which I use for all my other tools, and I want to get my R documentation in the same system I use for everything else.

Now, the question:

When I follow the tutorial to set up altdoc with mkdocs for my R package, I get this issue:

library(altdoc)
> setup_docs(tool = "mkdocs")
Error in `setup_docs()`:
✖ `altdoc` needs `mkdocs` to be installed in a Python virtual environment. The best way to create the required `.venv_altdoc` directory depends on your development environment. It usually involves
  executing commands like the following from the root directory of your R package.

I don't understand why altdoc requires mkdocs to be installed:

1. in any case, because the creation of these docs should be independent of their rendering with mkdocs
2. especially just to initialize the project.

Basically, I was hoping altdoc would just create the markdown output, which I could then integrate into a mkdocs site.
I don't need R to handle the actually running/building of mkdocs, I can do that using my existing workflow.
Basically, I'm imagining altdoc is doing this in 2 steps:

1. Convert from R documentation (eg .Rmd files, roxygen comments, etc) -> .md files.
2. Render those .md files into HTML using mkdocs build or mkdocs serve.

From my perspective, it seems like altdoc has tightly coupled these 2 things. I actually already have a workflow for the 2nd one; I only wanted altdoc to do the first. But then, I cannot use it, because it's forcing me to do both at the same time.

Part of the reason I don't want to just "install mkdocs to satisfy altdoc" is that in my workflow, I isolate my software in containers. I'm using an R container, so I don't want to add Python/mkdocs to this container, because I use a different container for that. So, this tight coupling makes altdoc too inflexible for my need.

Am I thinking about this the wrong way?

[nsheff]

It seems I can "trick" altdoc into working by just creating an empty file at altdoc/mkdocs.yml, and then I can run render_docs() and it appears to create some

It's unclear why I have to trick it like this, I couldn't find any documentation on how to configure this (I just inferred based on how altdoc was setting up a different type of output), and why initializing has this requirement for mkdocs to be installed when it doesn't actually need it.

[etiennebacher]

Hi, thanks for the nice words!

I don't understand why altdoc requires mkdocs to be installed:

1. [...]
2. especially just to initialize the project.

It is true mkdocs is not strictly needed to setup the documentation. However, the most common workflow is to setup and render the docs in the same environment, which means mkdocs has to be present at some point. When I use some tools, I expect the setup step to let me know if I'm missing some essential dependency. Letting the user set up the project and then error on the rendering because the key tool isn't there wouldn't be the best user experience IMO.

Basically, I was hoping altdoc would just create the markdown output, which I could then integrate into a mkdocs site.

I can see the value in that and it should probably be the case if the package was focused on producing mkdocs documentation only. However, we also support other tools and we have to take them into account when designing the API.

Also, I'm a bit reluctant to make the internals more complex than they already are. Finally, introducing a new intermediate function wouldn't remove the fact that we would require mkdocs in the setup step.

Am I thinking about this the wrong way?

I don't think you are, this seems like a valid usecase to me (although it seems quite rare). I'm just trying to weigh the pros and cons.

@vincentarelbundock what would you think about introducing a convert_docs() function that only produces the .md files? The overall workflow doesn't need to change (and we wouldn't highlight this new function) but it would allow doing just setup_docs() + convert_docs() in this usecase.

[nsheff]

Letting the user set up the project and then error on the rendering because the key tool isn't there wouldn't be the best user experience IMO.

To me, the problem is that you're forcing the user to do this by tightly coupling your workflow steps.
I guess my suggestion boils down to this: altdoc could be useful for another use case if you:

1. make the checks for mkdocs optional at setup (they could be opt-out, if you want to prioritize the current use cases).
2. decouple the two functions so I can use just the first half.

This doesn't seem to complicate things internally to me. In fact, it will make the code more clear by separation of concerns. The user interface you already using doesn't even have to change at all, just call the two functions sequentially.

Then, your package will be more modular and flexible, so it can be fit into existing workflows more easily, rather than prescribing a specific pattern on users.

[vincentarelbundock]

@vincentarelbundock what would you think about introducing a convert_docs() function that only produces the .md files? The overall workflow doesn't need to change (and we wouldn't highlight this new function) but it would allow doing just setup_docs() + convert_docs() in this usecase.

I would find this very useful! Especially if convert_docs() can target different outputs like Quarto and Markdown.

[vincentarelbundock]

Another (maybe simpler) option would be to have a new argument in the render_docs() function that would be TRUE if the user wants to call an external tool (Quarto or MkDocs) to render the docs. If FALSE, render_docs() would just prep the files.

That would have to disable the virtual environment checks, and place the render code in a if/else in .finalize_*().

[vincentarelbundock]

Better idea: Expose the .import_man() and .import_vignettes() functions to the users.

I would actually use this in one of my projects, where I current call internal altdoc functions with :::.

I might put a PR together eventually (or not).