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

links to source code in the Oscar documentation #588

Closed
ThomasBreuer opened this issue Jul 28, 2021 · 3 comments · Fixed by #3381
Closed

links to source code in the Oscar documentation #588

ThomasBreuer opened this issue Jul 28, 2021 · 3 comments · Fixed by #3381
Labels
documentation Improvements or additions to documentation

Comments

@ThomasBreuer
Copy link
Member

The Oscar documentation does currently not contain all links from docstrings to the source code.
The links seem to be missing for docstrings that belong to AA, Nemo, and Hecke.
(Note that the files in question get copied into the Oscar repository when the documentation gets built,
and then it is not clear to which addresses one should point for the source code.)

Is there an easy trick that would allow Documenter.jl to find the source code?

@fingolfin fingolfin added the documentation Improvements or additions to documentation label Feb 7, 2022
@fingolfin
Copy link
Member

I don't think Documenter.jl supports this at this time. And it'd be a bit difficult anyway, because it doesn't know which repository and which commit in that repository the code in question comes from. To be precise: I guess in principle it could be taught to deduced this information, at least in our specific case, but its code simply isn't prepared for this. The source link URLs are computed by this code:

            # When a source link is available then print the link.
            if !ctx.settings.disable_git
                url = Utilities.url(ctx.doc.internal.remote, ctx.doc.user.repo, result)
                if url !== nothing
                    push!(ret.nodes, a[".docs-sourcelink", :target=>"_blank", :href=>url]("source"))
                end
            end

So this delegates to the Utilities.url function; as you note, it already received the repo(sitory) as an argument. Looking at the declaration of the relevant url() methods, one finds this:

url(remote, repo, doc) = url(remote, repo, doc.data[:module], doc.data[:path], linerange(doc))

function url(remote, repo, mod, file, linerange)
    file === nothing && return nothing # needed on julia v0.6, see #689
    remote = getremote(dirname(file))
    isabspath(file) && isempty(remote) && isempty(repo) && return nothing
    ...

@fingolfin
Copy link
Member

Documenter.jl 1.0 was just released. Its changelog states among other things:

In addition to generating source and edit links for the main repository, Documenter can now also be configured to generate correct links for cases where some files are from a different repository (e.g. with vendored dependencies).

I have no idea how that works exactly, but it might be worth it having another look at this.

@lgoettgens
Copy link
Member

Documenter.jl 1.0 was just released. Its changelog states among other things:

In addition to generating source and edit links for the main repository, Documenter can now also be configured to generate correct links for cases where some files are from a different repository (e.g. with vendored dependencies).

I have no idea how that works exactly, but it might be worth it having another look at this.

#2927 handles the update to Documenter.jl v1.0, but skips handling this issue / everything with cross-references to keep the PR small and understandable.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
documentation Improvements or additions to documentation
Projects
None yet
Development

Successfully merging a pull request may close this issue.

3 participants