Online Documentation: improving navigation

[JimCircadian]

I imagine this might well have been discussed and / or considered, but as I find it a particular barrier to ease-of-learning with Julia (and am totally willing to contribute to change ) I wanted to ask this obviously amazing community: has anyone thought of putting an in-page navigation menu into the documentation?

As quite an experienced programmer, I tend to work on problems and enjoy exploring the full standard library documentation over time.

To give a concrete impression of what I’m struggling with: if I go to the arrays page of the docs here, I’ve got nooooo idea how to skim across the contents. And that page is BIG (which is amazing, but quite daunting!!!)

I appreciate there is the table of contents at the left hand side, but it would almost benefit from each section having a list of functions within it. If I click on “Array Functions”, I then have no idea how to get to eachrow unless I know that this function is already called “eachrow”.

Basically, I’m wondering if there is an index, or if we can create more detailed table of contents for each page that allow for easier navigation when you don’t know what it is you’re searching for? Has this ever been discussed?

I really love Julia! However, exploring the rich ecosystem in the core language is hard work for an experienced software engineer who has relished in getting some way into it, and then found the docs a bit hard to “explore”. If I could work towards helping improve the documentation or at least understand the previous discussion around items like this, then that’d be amazing.

Thanks in advance

[cormullion]

You might be interested in this issue, and there are quite a few more issues there which discuss possible improvements.

[JimCircadian]

That’s amazing, thank you @cormullion, exactly what I was trying to pick up on. Will review and see how this can factor into some community contribution vibes for me.

[goerz]

@JimCircadian

if I go to the arrays page of the docs here , I’ve got nooooo idea how to skim across the contents

I would hope that Add support for `CollapsedDocStrings` in `@meta` block by goerz · Pull Request #2394 · JuliaDocs/Documenter.jl · GitHub goes a long way at alleviating that particular problem. The feature is already merged, so it should be available in the next Documenter release. (However, the Julia docs would also have to update to that Documenter release and set up that the docstrings on that page should be collapsed by default)

P.S.: As a first step, the Julia docs should also update to a more recent version of Documenter, that allows you to collapse those docstrings manually. You’ll see that working in the 1.11-dev docs, so the situation should already be better when 1.11 is officially released.