Allow linking of files not in docs directory as pages in makedocs

[christopher-dG]

I'm not sure if this is possible, but I'd really love to do the following in my make.jl:

makedocs(
    # ...
    pages=[
        # ...,
        "Index" => "../README.md",
        "Contibuting" => "../CONTRIBUTING.md",
        # ...,
    ],
    # ...
)

I tried it and received the following error:

ERROR: LoadError: '../CONTRIBUTING.md' is not an existing page!
Stacktrace:
 [1] walk_navpages(::Bool, ::String, ::String, ::Array{Any,1}, ::Void, ::Documenter.Documents.Document) at /home/degraafc/.julia/v0.6/Documenter/src/Builder.jl:154
 [2] walk_navpages(::Pair{String,String}, ::Void, ::Documenter.Documents.Document) at /home/degraafc/.julia/v0.6/Documenter/src/Builder.jl:171
 [3] collect_to!(::Array{Documenter.Documents.NavNode,1}, ::Base.Generator{Array{Any,1},Documenter.Builder.##3#4{Void,Documenter.Documents.Document}}, ::Int64, ::Int64) at ./array.jl:474
 [4] collect(::Base.Generator{Array{Any,1},Documenter.Builder.##3#4{Void,Documenter.Documents.Document}}) at ./array.jl:442
 [5] walk_navpages(::Array{Any,1}, ::Void, ::Documenter.Documents.Document) at /home/degraafc/.julia/v0.6/Documenter/src/Builder.jl:172
 [6] runner(::Type{Documenter.Builder.SetupBuildDirectory}, ::Documenter.Documents.Document) at /home/degraafc/.julia/v0.6/Documenter/src/Builder.jl:124
 [7] dispatch(::Type{Documenter.Builder.DocumentPipeline}, ::Documenter.Documents.Document) at /home/degraafc/.julia/v0.6/Documenter/src/Selectors.jl:164
 [8] cd(::Documenter.##2#3{Documenter.Documents.Document}, ::String) at ./file.jl:70
 [9] #makedocs#1(::Bool, ::Array{Any,1}, ::Function) at /home/degraafc/.julia/v0.6/Documenter/src/Documenter.jl:198
 [10] (::Documenter.#kw##makedocs)(::Array{Any,1}, ::Documenter.#makedocs) at ./<missing>:0
while loading /home/degraafc/code/PkgTemplates/docs/make.jl, in expression starting on line 3

Maybe I'll take a closer look at the code when I have time to make a PR.

[mortenpi]

Currently makedocs assumes that all the pages live within the document. However, this sounds like a good feature, so if you'd like to take a stab at implementing it, that would be awesome.

I think it would be nice to be explicit about it though and not rely simply on relative links. So I would propose wrapping it in a separate function (similar to the current hide), e.g.

makedocs(
    # ...
    pages=[
        "Contibuting" => external("../CONTRIBUTING.md"),
    ]
)

Not sure what a good name for the function would be.

[willow-ahrens]

For others who run into this issue, I've had success using symlinks for precisely this purpose. I navigate to the docs/src directory and run ln -s ../../CONTRIBUTING.md CONTRIBUTING.md.

[mortenpi]

I think with symlinks the edit links won't quite point to the right place though, so you may still want to have EditURL set in the linked file.

[odow]

Rather than bringing in external source files, I think the appropriate thing to do here might be to link to the external URL. (Since the OP is really asking to, for example, link to a GitHub readme or contributing guide.)

In which case, we could close this issue in favor of: https://github.com/JuliaDocs/Documenter.jl/issues/344