`modules` argument to `makedocs()` conflates availability with doctests
staticfloat opened this issue · comments
If I need to include the docstring of one of my dependencies I must include that dependency as one of the modules passed to makedocs(), if I do not the docstring cannot be found. However if I do, then (a) I get a bunch of warnings if some of the docstrings for that module are not included in my docs output, and (b) if one of the doctests fails, my build fails.
I think the ideal behavior here is for docstrings referenced explicitly by module to work without needing to provide the owning module as an argument to makedocs().
Example repository showcasing the issue is here: https://github.com/staticfloat/DocumenterModuleProblem.jl
As written, we have a top-level module with a dependency (BrokenDoctest) that, as its name suggests, has a broken doctest. If I try to run the build, it fails. However if I remove BrokenDoctest from the list of modules, I get an error that BrokenDoctest.broken cannot be found.
Looking at the code, this seems to be quite deliberate. But, it's not documented behavior, and I don't think it makes any sense. I agree that setting modules should just check that every public member of the given modules has its docstring rendered in the documentation, and nothing else. It should not limit docstrings that can be rendered to only those from the given modules.
I've run into this myself, and it's the reason I don't use the modules argument.