Hierarchical documentation structure

[gdalle]

Fixes #74

Main contributions:

• Categorize documentation pages into: First steps, Graph types, Core functions, Algorithms, Advanced
• Include all docstrings in the docs, each only once
• Fix most documentation building bugs, so that the warnings / errors we get are actually informative
• Clean up README and other Markdown files

[etiennedeg]

Many links do not exist anymore, notably url of the form docs/src/<problem>.md. These are replaced by docs/src/algorithms/<problem>.md. Maybe we should add redirection on these old links ?

[gdalle]

Many links do not exist anymore, notably url of the form docs/src/<problem>.md. These are replaced by docs/src/algorithms/<problem>.md. Maybe we should add redirection on these old links ?

@etiennedeg what links are you referring to? Do you know a way to redirect without keeping a copy of these markdown files in the docs folder?

[codecov]

Codecov Report

Merging #114 (962d8c8) into master (3628517) will not change coverage.
The diff coverage is 100.00%.

@@           Coverage Diff           @@
##           master     #114   +/-   ##
=======================================
  Coverage   97.54%   97.54%           
=======================================
  Files         109      109           
  Lines        6318     6318           
=======================================
  Hits         6163     6163           
  Misses        155      155           

[etiennedeg]

I think the urls such as https://juliagraphs.org/Graphs.jl/dev/pathing/ will no longer exist, and outside pages may still refer to the old version of the documentation, for example in discourse answers. Keeping a copy of these markdown files could work, but there is maybe a way to add redirection with Documenter.jl. Maybe there is some kind of policy for this in the Julia ecosystem, I don't know...

[gdalle]

I see what you mean. Note however that we won't have this problem for links that refer to the stable documentation, it's only for those that choose to point to the dev version (which is a bold choice)

[gdalle]

This could help in the long run JuliaDocs/Documenter.jl#1411.
But in the meantime, I think what we should do is create a custom 404 page using https://docs.github.com/en/pages/getting-started-with-github-pages/creating-a-custom-404-page-for-your-github-pages-site, saying something like

The URL you entered is incorrect. You may be trying to access an old version of the Graphs.jl documentation. For the latest version, go to...

[gdalle]

@etiennedeg what do you think about an error message like this one: https://github.com/gdalle/Test404? Enough for the time being?

[etiennedeg]

Yes, I don't think this is that much of an issue, don't spend much time on it if Documenter.jldoesn't provides 404 pages.

[gdalle]

I'm not very familiar with the PR review process, how many approvals of JuliaGraphs members should I gather before I can merge?

[etiennedeg]

Just one, I will take a look

[matbesancon]

I am fine with the pages not existing anymore producing errors. People will then go back to the root and explore from there

[matbesancon]

while we're at it @gdalle can you activate in this PR previews for the doc page? See https://juliadocs.github.io/Documenter.jl/stable/lib/public/#Documenter.deploydocs

[gdalle]

while we're at it @gdalle can you activate in this PR previews for the doc page? See https://juliadocs.github.io/Documenter.jl/stable/lib/public/#Documenter.deploydocs

I could but it doesn't work for forks anyway so...

[gdalle]

@etiennedeg I took your remarks into account, I also renamed the Graph types section into Ecosystem in case we want to expand it later. Go for merge as soon as the tests pass (or randomly fail on Windows / MacOS 😅) ?

[etiennedeg]

After that, I think we are good