Skip to content
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.

Sign up for GitHub

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

Jump to bottom

A way to excluding some submodules from missingdocs #2233

Open
frankier opened this issue Aug 24, 2023 · 1 comment · May be fixed by #2377
Open

A way to excluding some submodules from missingdocs #2233

frankier opened this issue Aug 24, 2023 · 1 comment · May be fixed by #2377
Labels
Type: Enhancement

Comments

@frankier
Copy link
Contributor

Currently for each module passed to makedocs will all submodules recursively defined and added to the list of modules checked by missingdocs.

I have a few modules which vendored into my package. e.g. if a small dependency is not externally maintained/hasn't got around to merging a PR. These modules are meant to be transitional and the hope is they might be removed at some point. They are not part of the public interface, but I don't want to go through and strip the docs.

I'm not sure what the best solution is. Perhaps some parts of the subtree can be excluded with a internal_modules argument?

This is a bit more relevant with the new strict=true behaviour. There should be a more granular way of turning off this warning/error: #2051

Related to this is efforts to have some degree of public/private added to Julia which might help JuliaLang/julia#50105
@mortenpi
Copy link
Member

So, the current standard way to work around this is to include all the internal docstrings on an internals page with at-autodocs. But I agree, that's not necessarily ideal.

I think I would be okay with a internal_modules / missingdocs_exclude keyword where you list the modules you don't want checked. Two questions that I have:

  1. Are you still allowed to include docstrings from those modules? I.e. is it declaring the module "internal" and therefore should not be included? Or is it just excluding them from this check?
  2. This would have module-level granularity. But maybe there's some more general API we could devise here? User-provided predicate that gets called with each (missing) docstring?

Also, in general, allowing more fine-grained control over the errors would always be good, so API suggestions in that directions would be very welcome too.

@frankier frankier linked a pull request Dec 13, 2023 that will close this issue
Open
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
Type: Enhancement
Projects
None yet
Milestone
No milestone
Development

Successfully merging a pull request may close this issue.

Add checkdocs_ignore to exclude certain modules from checkdocs frankier/Documenter.jl
2 participants
@mortenpi @frankier