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.

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

Handle bad doc metadata better in at-autodocs #1811

Merged
merged 7 commits into from
May 8, 2022
Merged

Conversation

mortenpi
Copy link
Member

@mortenpi mortenpi commented May 4, 2022

When running into the call syntax issue in #1810 or #1192, at-autodocs will now issue a standard documenter error/warning:

┌ Error: @autodocs (src/index.md:1-4) encountered a bad docstring binding 'Docerr.foo'
│ ```@autodocs
│ Modules = [Docerr]
│ Order   = [:function, :type]
│ ```
│ This is likely due to a bug in the Julia docsystem relating to the handling of
│ docstrings attached to methods of callable objects. See:
│ 
│   https://github.com/JuliaLang/julia/issues/45174
│ 
│ As a workaround, the docstrings for the functor methods could be included in the docstring
│ of the type definition. This error can also be ignored by disabling strict checking for
│ :autodocs_block in the makedocs call with e.g.
│ 
│   strict = Documenter.except(:autodocs_block)
│ 
│ However, the relevant docstrings will then not be included by the @autodocs block.
│   exception = UndefVarError: foo not defined
└ @ Documenter.Expanders ~/Julia/JuliaDocs/Documenter/src/Utilities/Utilities.jl:32

If strict error checking is disabled, then these docstrings will simply get omitted from the at-autodocs block. This will close #1810 and close #1192 on Documenter's end, but the upstream issue JuliaLang/julia#45174 still needs to be addressed.

In addition, this add the Documenter.except function to easily disable strict checking on some error types (as opposed to having to list all, except a few manually):

makedocs(...,
    strict = Documenter.except(:linkcheck, :footnote),
)

And we also now print the error classes that cause makedocs to terminate, so that it would be easier to figure out which error classes to except, if that is something the user wants / needs to do.

@mortenpi mortenpi mentioned this pull request May 4, 2022
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
1 participant