Deploy docs with clean URLs

[mortenpi]

Switch the deployed docs to cleaner URLs like manual/linalg/ instead of manual/linalg.html. Requires Documenter v0.11.0.

The new Documenter version brings a couple of other updates as well, most importantly a decent mobile experience (many thanks to @wookay for that). I hope I'm not too late to the party, but it would be great to have this for the 0.6 release docs as well.

There are a couple of loose ends:

• Local builds should still go with the page.md -> page.html convention, i.e. html_prettyurls should be false for them. I made the option depend on the deploy argument, and I propose two different targets for the docs Makefile -- html for local builds and a separate deploy just for deploying from Travis. But it also requires support from the main Makefile, and I could use some advice there.
• One of the links in the manual is broken due to a bug in Documenter (ref to "Unicode Input" in manual/interacting-with-julia.md).
• Updated Documenter also complains about links that start with a #, but that doesn't actually break any URLs in the output.
• Broken search links.

An example build of the manual: http://mortenpi.eu/julia/pretty-urls/

[tkelman]

would be good to diff the generated html before vs after this. I'm a bit nervous that the refactorings here might change some of the windows backslash fixes I had to make in Documenter.

[mortenpi]

Good point, but it seems to look fine. I kept the replacements intact and all the path math should go through the relhref function anyway, where the replacement is definitely being done.

Windows builds of the docs are available here: https://github.com/mortenpi/julia/tree/gh-pages

I also have a tidyed diff for search.html/search/index.html with v0.10.3 and v0.11.0, respectively: https://gist.github.com/mortenpi/f328e2d2419647384f8b7d5d77b64f79

And when grepping for double backslashes I didn't see any that were in links.

I built Julia under Cygwin for this, and I also checked that the broken URLs were indeed present when building the docs with Documenter v0.9.0, which didn't have your fixes yet.

[tkelman]

do you have a pointer to make docs on what this is doing? not a pattern I see often

[mortenpi]

Sets the ARGS variable, but only for the deploy target, and it gets passed on to all the dependencies, hence I can use it in html. https://www.gnu.org/software/make/manual/make.html#Target_002dspecific

But I have no idea if this is a good pattern to use or not, just the only thing that came to mind.

[mortenpi]

I.e. the only thing which wouldn't involve copying the whole html target.

[tkelman]

so what will ARGS be when running the html target? empty?

[mortenpi]

Yup. The command that gets executed in my case is

/home/morten/Julia/julia/build/usr/bin/julia /home/morten/Julia/julia/doc/make.jl --

It might be a good idea to explicitly set it in the Makefile though, to make that clear.

[tkelman]

makefiles are confusing enough that unless we eventually start using a system that is actually auto-generating them, readable is probably preferable to overly-clever for the sake of brevity

[mortenpi]

I got rid of the variable magic. I didn't copy the Windows-specific part for the deploy target since it's not really relevant on Travis. Any thoughts on how to integrate this into .travis.yml or the main Makefile though? A make -C doc/ deploy somewhere?

[jebej]

Currently, clicking on search results does not work: JuliaDocs/Documenter.jl#495

[mortenpi]

Various path issues fixed by v0.11.1. The "Unicode Input" link issue was due to the page being listed twice in pages (ideally Documenter would detect this situation; JuliaDocs/Documenter.jl#497). Example build updated: http://mortenpi.eu/julia/pretty-urls/

Could still use some advice on how to incorporate this into .travis.yml so that the docs would deploy automatically.

[tkelman]

let's also bump this to 0.25.2 0.25.2+ to get rid of some deprecation warnings

[mortenpi]

Done.

[mortenpi]

So, putting the deploy step into after_success feels reasonable. It seems to run OK.

[tkelman]

looks like there are a few invalid links?

369.426951  !! Invalid local link: unresolved path
369.427061     'linalg.html#stdlib-blas-side-1' in stdlib/linalg.md
369.427100  !! Invalid local link: unresolved path
369.427120     'linalg.html#stdlib-blas-uplo-1' in stdlib/linalg.md

 !! Invalid local link: unresolved path
    '../numbers/#Core.Float64' in stdlib/arrays.md

[mortenpi]

Yup -- I think they are from commits that came after the one this PR is forked from. I'll rebase before merge and fix them, but is there anything else besides this?

[tkelman]

don't think so. I'd leave off the trailing / in make -C doc/ but that's pretty inconsequential

[mortenpi]

It turns out that those "invalid links" were Documenter errors after all. In short -- if the same docstring gets included multiple times then Documenter currently calls fixlinks! multiple times on it, and complains on the second time since the link is already fixed. But it shouldn't break anything in the output, so I'd leave fixing that for another day (JuliaDocs/Documenter.jl#505).

A separate issue is why we have multiple copies of a docstring in the first place. The ../numbers/#Core.Float64 one comes from speye, where Base.SparseArrays.speye(::SparseMatrixCSC) in the manual also includes the docstring for Base.SparseArrays.speye(::Type, ::Integer, ::Integer), which looks like a bug in Documenter to me.

The linalg.html ones come from the symm function, which had both Base.LinAlg.BLAS.symm(::Char, ::Char, ::Any, ::Any, ::Any) and Base.LinAlg.BLAS.symm(::Any, ::Any, ::Any, ::Any, ::Any) listed. The one with Chars doesn't have a docstring actually, so I removed the reference for that. Whether the one with ::Chars should match the one with only ::Anys in the first place, I am not actually sure -- I don't think the type signature matching logic is clearly documented in Documenter at the moment.

In any case I would leave these for another day as well (JuliaDocs/Documenter.jl#506).

Removed the / -- consistent with the rest this way.

[tkelman]

@mortenpi oops, this makes linkcheck fail - should probably skip linkchecking on relative references