-
Notifications
You must be signed in to change notification settings - Fork 9
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Why the requirement for mkdocs to be installed? #298
Comments
It seems I can "trick" altdoc into working by just creating an empty file at 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. |
Hi, thanks for the nice words!
It is true
I can see the value in that and it should probably be the case if the package was focused on producing 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
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 |
To me, the problem is that you're forcing the user to do this by tightly coupling your workflow steps.
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. |
I would find this very useful! Especially if |
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:
I don't understand why altdoc requires mkdocs to be installed:
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:
.md
files.mkdocs build
ormkdocs 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?
The text was updated successfully, but these errors were encountered: