Remove @extref from non-Documenter output #245
Conversation
Recent versions of Documenter use `@extref` link to documentation of external packages. Remove these in the same way and under the same conditions as `@ref` and `@id` tags.
|
Thanks a lot! Really appreciate that it comes with test and changelog. |
| - Documenter style `@ref`s and `@id` will be removed. This means that you can use | ||
| `@ref` and `@id` in the source file without them leaking to the script. | ||
| - Documenter style `@ref`s, `@extref`s and `@id` will be removed. This means that you can use | ||
| `@ref`, `@extref` and `@id` in the source file without them leaking to the script. |
There was a problem hiding this comment.
This is the only place in the docs where I see the existing functionality mentioned.
Oddly it is in the context of a keyword argument feature that is deprecated in the source, but the deprecation is not mentioned in the docs.
There was a problem hiding this comment.
It is discussed a bit here: https://fredrikekre.github.io/Literate.jl/v2/documenter/ but perhaps it can be improved.
There was a problem hiding this comment.
Yes, that's the page I was looking at. The first paragraph gave me the impression that this is all dependent on documenter = (true|false), which left me confused until I saw the deprecation notice in the changelog.
The generators (Literate.markdown, Literate.notebook and Literate.script) supports a keyword argument documenter that lets the generator perform some extra things, keeping in mind that the source code have been written with Documenter.jl in mind. So let's take a look at what will happen if we set documenter = true:
There was a problem hiding this comment.
Yea you are right. It should be updated to use Literate.markdown(...; flavor = DocumenterFlavor()).
|
Oh, that was faster than expected! Thank you for the package! |
|
Release: JuliaRegistries/General#105051 |
|
You merged and released this before I managed to get my CI building docs with my patch. Simplifies my life 😺 |
3 participants
I am unsure whether this is a bug fix or a new feature.
Recent versions of Documenter use
@extreflinks to refer to the documentation of external packages.This was introduced in JuliaDocs/Documenter.jl#2366 and JuliaDocs/Documenter.jl#2424 and currently is documented at https://documenter.juliadocs.org/stable/man/syntax/#@extref-link.
This pull request removes
@extreflinks in the same way and under the same conditions as@refand@idtags.This is technically a breaking change if it is not considered a bug fix. It seems natural though, especially if the
@extrefsyntax becomes more widely adopted.I attempted to write a changelog entry but it is quite likely that I got the syntax wrong.