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

Insert hardcoded backlinks to stdlib doc pages #51375

Merged
merged 3 commits into from
Jan 16, 2024
Merged

Conversation

LilithHafner
Copy link
Member

This is #48814 times 25. It solves most of but not all of #50035.

To quote @mortenpi from #48814 (review)

Seems like a reasonable workaround for now, but should be removed once we have a proper fix.

I ran this code to generate the diff:

function insert_edit_link(source, target)
    prefix = """
    ```@meta
    EditURL = "$target"
    ```

    """
    contents = read(source, String)
    startswith(contents, prefix) && return
    occursin("EditURL", contents) && throw("\"EditURL\" already exists in $source")
    write(source, prefix * contents)
end

haslocaldocs(stdlib) = isfile("stdlib/$stdlib/docs/src/index.md")
isjll(stdlib) = endswith(stdlib, "_jll")

function go()
    stdlibs = filter!(!isjll, first.(values(Pkg.Types.get_last_stdlibs(VERSION))))
    localstdlibs = filter(haslocaldocs, stdlibs)
    for stdlib in localstdlibs
        insert_edit_link("stdlib/$stdlib/docs/src/index.md", "https://github.com/JuliaLang/julia/blob/master/stdlib/$stdlib/docs/src/index.md")
    end
    println("TODO: $(filter(!haslocaldocs, stdlibs))")
end

go()
# TODO: ["ArgTools", "SparseArrays", "NetworkOptions", "Downloads", "LibCURL", "SuiteSparse", "Pkg", "Tar", "SHA"]

@LilithHafner
Copy link
Member Author

This and the 7 PRs that I just linked to it fix #50035.

While it is unfortunate to hardcode these URLs, hardcoding canonical URLs in a project that spans many repos seems like a reasonable use of hardcoding. Also, it is unacceptable to have these links broken because it is uninviting to potential new contributors.

The final code I used is
function insert_edit_link(source, target)
    prefix = """
    ```@meta
    EditURL = "$target"
    ```

    """
    contents = read(source, String)
    startswith(contents, prefix) && return
    occursin("EditURL", contents) && throw("\"EditURL\" already exists in $source")
    write(source, prefix * contents)
end

haslocaldocs(stdlib) = isfile("stdlib/$stdlib/docs/src/index.md")
isjll(stdlib) = endswith(stdlib, "_jll")

function go()
    stdlibs = filter!(!isjll, first.(values(Pkg.Types.get_last_stdlibs(VERSION))))
    for stdlib in filter(haslocaldocs, stdlibs)
        insert_edit_link("stdlib/$stdlib/docs/src/index.md", "https://github.com/JuliaLang/julia/blob/master/stdlib/$stdlib/docs/src/index.md")
    end
    println("TODO: $(filter(!haslocaldocs, stdlibs))")
end

go()
# TODO: ["ArgTools", "SparseArrays", "NetworkOptions", "Downloads", "LibCURL", "SuiteSparse", "Pkg", "Tar", "SHA"]

for stdlib in ["ArgTools", "SparseArrays", "NetworkOptions", "Downloads", "LibCURL", "Tar", "SHA"]
    git_url = split(collect(readlines("stdlib/$stdlib.version"))[3], " := ")[2]
    target = "../../dev/_$stdlib"
    isdir(target) || run(`git clone $git_url $target`)
    cd(target) do
        insert_edit_link("docs/src/index.md", "$(splitext(git_url)[1])/blob/master/docs/src/index.md")
        run(`git checkout -b lh/hardcode-backlinks`)
        run(`git commit docs/src/index.md -m "Hardcode doc edit backlink"`)
    end
end

I created the actual pull requests by hand.

@fredrikekre
Copy link
Member

I believe all of this will be fixed by #47105, cc @mortenpi

@LilithHafner
Copy link
Member Author

That would be lovely! Though I'm having trouble finding a recently merged PR to Doccumetner.jl that would fix this.

@fredrikekre
Copy link
Member

See references under "The handling of remote repository (e.g. GitHub) URLs has been overhauled" in Documenters changelog.

@mortenpi
Copy link
Contributor

mortenpi commented Sep 18, 2023

I believe all of this will be fixed by #47105, cc @mortenpi

Yes. This specific issue was the primary motivation for the remote link overhaul.

#47105 is running into some trouble with our CI setup though that needs to be debugged. I'll try to get to it this week, but if someone else beats me to it, that would make me very happy 🙂

I would suggest closing the standard library PRs before they get merged and reverting the SHA.jl one though.

I had completely forgotten about the Dates change -- I'll revert that in my PR (as it's no longer necessary).

@LilithHafner
Copy link
Member Author

Thanks for making a better and more general fix than this! I was going to hack it because these links have been broken for a long time, but I'd much rather see it fixed in Documenter.jl. Thanks! I'll make a PR to revert the SHA one once #47105 merges.

@LilithHafner
Copy link
Member Author

Three months have passed and the issue keeps on getting reported, I'm going to merge this as a stopgap if nobody objects. We can always revert it later

cc @fredrikekre @mortenpi

@mortenpi
Copy link
Contributor

I guess it makes sense to have the workaround for now. There's a WIP "proper" fix in JuliaDocs/Documenter.jl#2372, but it's still not fully working (inviting a review there, to figure out why that is), and I can't really promise a timeline.

@LilithHafner LilithHafner merged commit a327a95 into master Jan 16, 2024
5 of 7 checks passed
@LilithHafner LilithHafner deleted the stdlib-backlinks branch January 16, 2024 23:09
KristofferC pushed a commit that referenced this pull request Jan 24, 2024
This is #48814 times 23. It solves most of but not all of #50035.

(cherry picked from commit a327a95)
@KristofferC KristofferC mentioned this pull request Jan 24, 2024
33 tasks
KristofferC added a commit that referenced this pull request Feb 6, 2024
Backported PRs:
- [x] #51095 <!-- Fix edge cases where inexact conversions to UInt don't
throw -->
- [x] #52583 <!-- Don't access parent of triangular matrix in powm -->
- [x] #52645 <!-- update --gcthreads section in command line options -->
- [x] #52423 <!-- update nthreads info in versioninfo -->
- [x] #52721 <!-- inference: Guard TypeVar special case against vararg
-->
- [x] #52637 <!-- fix finding bundled stdlibs even if they are e.g.
devved in an environment higher in the load path -->
- [x] #52752 <!-- staticdata: handle cycles in datatypes -->
- [x] #52758 <!-- use a Dict instead of an IdDict for caching of the
`cwstring` for Windows env variables -->
- [x] #51375 <!-- Insert hardcoded backlinks to stdlib doc pages -->
- [x] #52994 <!-- place work-stealing queue indices on different cache
lines to avoid false-sharing -->
- [x] #53015 <!-- Add type assertion in iterate for logicalindex -->
- [x] #53032 <!-- Fix a list in GC devdocs -->
- [x] #52748 
- [x] #52856 
- [x] #52878
- [x] #52754 
- [x] #52228
- [x] #52924
- [x] #52569 <!-- Fix GC rooting during rehashing of iddict -->
- [x] #52605 <!-- Default uplo in symmetric/hermitian -->
- [x] #52618 <!-- heap snapshot: add gc roots and gc finalist roots to
fix unrooted nodes -->
- [x] #52781 <!-- fix type-stability bugs in Ryu code -->
- [x] #53055 <!-- Profile: use full terminal cols to show function name
-->
- [x] #53096 
- [x] #53076 
- [x] #52841 <!-- Extensions: make loading of extensions independent of
what packages are in the sysimage -->
- [x] #52078 <!-- Replace `&hArr;` by `&harr;` in documentation -->
- [x] #53035 <!-- use proper cache-line size variable in work-stealing
queue -->
- [x] #53066 <!-- doc: replace harr HTML entity by unicode -->
- [x] #52996 <!-- Apple silicon has 128 byte alignment so fix our
defines to match -->
- [x] #53121 

Non-merged PRs with backport label:
- [ ] #52694 <!-- Reinstate similar for AbstractQ for backward
compatibility -->
- [ ] #51479 <!-- prevent code loading from lookin in the versioned
environment when building Julia -->
@KristofferC KristofferC removed the backport 1.10 Change should be backported to the 1.10 release label Feb 6, 2024
Drvi pushed a commit to RelationalAI/julia that referenced this pull request Jun 7, 2024
This is JuliaLang#48814 times 23. It solves most of but not all of JuliaLang#50035.

(cherry picked from commit a327a95)
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
docs This change adds or pertains to documentation stdlib Julia's standard library
Projects
None yet
Development

Successfully merging this pull request may close these issues.

4 participants