Including doc pages from other packages

[timholy]

This is another "org-level" question (similar to #301): in the org-level docs, I'd like to include a page from one of the org's packages. I tried adding Pkg.dir(...) to pages = [...] in makedocs, and got

julia> include("make.jl")
Documenter: setting up build directory.
ERROR: LoadError: '/home/tim/.julia/v0.5/ImageCore/docs/src/views.md' is not an existing page!
 in walk_navpages(::String, ::Void, ::Documenter.Documents.Document) at /home/tim/.julia/v0.5/Documenter/src/Builder.jl:163
 in 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:340
 in collect(::Base.Generator{Array{Any,1},Documenter.Builder.##3#4{Void,Documenter.Documents.Document}}) at ./array.jl:308
 in walk_navpages(::Array{Any,1}, ::Void, ::Documenter.Documents.Document) at /home/tim/.julia/v0.5/Documenter/src/Builder.jl:149
 in runner(::Type{Documenter.Builder.SetupBuildDirectory}, ::Documenter.Documents.Document) at /home/tim/.julia/v0.5/Documenter/src/Builder.jl:124
 in dispatch(::Type{Documenter.Builder.DocumentPipeline}, ::Documenter.Documents.Document) at /home/tim/.julia/v0.5/Documenter/src/Selectors.jl:164
 in cd(::Documenter.##2#3{Documenter.Documents.Document}, ::String) at ./file.jl:59
 in #makedocs#1(::Bool, ::Array{Any,1}, ::Function) at /home/tim/.julia/v0.5/Documenter/src/Documenter.jl:159
 in (::Documenter.#kw##makedocs)(::Array{Any,1}, ::Documenter.#makedocs) at ./<missing>:0
 in include_from_node1(::String) at ./loading.jl:488
while loading /home/tim/src/juliaimages.github.io/docs/make.jl, in expression starting on line 3

but

shell> ls /home/tim/.julia/v0.5/ImageCore/docs/src/views.md
/home/tim/.julia/v0.5/ImageCore/docs/src/views.md

Moreover this page links to assets (images) for in-line display. Thoughts on the recommended way to proceed? I could copy the source files, but that seems a little yucky.

[mortenpi]

Only the Markdown files under makedocs' source directory are "available" for Documenter (as it is implemented right now). Under the hood it first reads all the .md files from source and then, when parsing pages, it just checks if the page is loaded.

In order to support this, we should probably figure out a nice way of referring to pages outside source. I'm not sure that absolute paths are the best option here. Perhaps ImageCore:/docs/src/views.md or some URL scheme instead?

But I am not sure if we should support this out-of-the-box at all. Perhaps we could make Documenter's guts a bit more accessible for power users? I was at one point doing something like this -- constructing the Documents.Document object manually, modifying it by adding more pages to it and then calling the build commands myself. Would be nice to formalize some APIs for this kind on thing though, I suppose.

[MichaelHatherly]

In order to support this, we should probably figure out a nice way of referring to pages outside source.

I'm not too sure whether that's actually possible in any kind of general way since anything outside of the current package doesn't really have a relative path. I think it's probably simplest to just use full URLs to wherever the page happens to be hosted, rather than require one package's docs to first require building another package's docs.

Would be nice to formalize some APIs for this kind on thing though, I suppose.

We can definitely do something along those line, though I need to get #184 finished, which will make things much more straightforward I'm sure.

[timholy]

With regards to relative path, I'm not sure why dirname(page) wouldn't work.

But certainly I can embed links to other pages. I'll start there and see how it feels.

[timholy]

I realized I was needlessly vague above. To be concrete, here's what I was trying:

makedocs(format   = :html,
         sitename = "JuliaImages",
         pages    = ["Home"=>"index.md", "install.md", "arrays_colors.md", Pkg.dir("ImageCore", "docs", "src", "views.md"), "troubleshooting.md"])

[MichaelHatherly]

With regards to relative path, I'm not sure why dirname(page) wouldn't work.

If we just copy any files over that are not found in source then it kind of works, but you then run the risk of overwriting any pages that happen to have the same filenames. There's also the possibility the a copied page might depend on other things in the docs/ config where it was copied from.

Best bet is to either just use full URLs to the address where the page is hosted, or to build a single "mega-doc" that contains all the docs and docstrings for all Images-related packages in one interlinked site rather than splitting it up over several.