Confused about docs #885

Activity

1. oxinabox commented on Dec 18, 2023

   

   oxinabox

   on Dec 18, 2023

   MemberAuthor

   More actions

   The stable docs don't seem to mention popfirst! at all: https://juliacollections.github.io/DataStructures.jl/stable/search/?q=popfirst%21

   The dev docs do: https://juliacollections.github.io/DataStructures.jl/dev/search/?q=popfirst%21

   The very purpose of the dev docs is to be the docs for the currently in dev (i.e. not released) version of the package.

   You can change which version of the docs you are looking at with the menu selector one the side:
   (Which moves between versions of the docs as on the dev version we have been)
   
   

   There is hardly any churn, this package is very slow moving, and hasn't released breaking changes in years.
   These changes are needful to get us to 1.0, where we are consistent with the names of all the functions in Base (#479).
   Which is taking a long time, due to limited time people have to work on this.
2. aoanla commented on Dec 18, 2023

   

   aoanla

   on Dec 18, 2023 via email

   More actions

   Hm, the actual problem is that neither 'stable' nor 'dev' are linked to by quite a lot of other places (including the top search engine hits) - they instead link to 'latest' (which, itself, silently picks 'dev' - presumably as it's the top of the list - but retains 'latest' in the URL ) https://juliacollections.github.io/DataStructures.jl/latest/ I assert that this is misleading - most people looking for the "latest" docs mean "latest stable" - and is made worse by the fact that the only way to tell what version "latest" has picked (and that it isn't a stable release) is to examine the version selector at the bottom right (which is *hidden by default* on mobile, for example). This is fairly poor UI - dev versions should at least have a 'This documentation is for a development release' style banner somewhere on the page, especially if 'latest' is going to silently select them.

   …

   On Mon, 18 Dec 2023, 06:51 Frames White, ***@***.***> wrote: The *stable* docs don't seem to mention popfirst! at all: https://juliacollections.github.io/DataStructures.jl/stable/search/?q=popfirst%21 The *dev* docs do: https://juliacollections.github.io/DataStructures.jl/dev/search/?q=popfirst%21 The very purpose of the *dev* docs is to be the docs for the currently in dev (i.e. not released) version of the package. You can change which version of the docs you are looking at with the menu selector one the side: (Which moves between versions of the docs as on the dev version we have been) image.png (view on web) <https://github.com/JuliaCollections/DataStructures.jl/assets/5127634/c086a4fe-1f57-45b9-afe8-307d9b5f84d3> image.png (view on web) <https://github.com/JuliaCollections/DataStructures.jl/assets/5127634/5c0dbdf4-1e40-4666-a952-49c2fd1017aa> There is hardly any churn, this package is very slow moving, and hasn't released breaking changes in years. These changes are needful to get us to 1.0, where we are consistent with the names of all the functions in Base (#479 <#479>). Which is taking a long time, due to limited time people have to work on this. — Reply to this email directly, view it on GitHub <#885 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/ABNRWLJDZFQZTLIPVVNDDZ3YJ7RVVAVCNFSM6AAAAABAZAUX56VHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMYTQNJZGY2TANRZGA> . You are receiving this because you were mentioned.Message ID: ***@***.***>
3. oxinabox commented on Dec 19, 2023

   

   oxinabox

   on Dec 19, 2023

   MemberAuthor

   More actions

   That's a good suggestion.
   I have opened a issue on Documenter.jl to see if we can get that feature added.
   JuliaDocs/Documenter.jl#2382

   We also should run the script linked in JuliaDocs/Documenter.jl#1577
   to make sure our outdated docs have the outdated banner.