Include local build

[SimeonEhrig]

Hi, we want to use MultiDocumenter.jl to document our QEDjl-project. The project contains a meta package QED.jl and some sub packages. QED.jl compiles all sub packages together and reexport the API. Therefore QED.jl has only a small documentation with few general things. Most of the documentation is located to in the sub packages.

Therefore we want to use MultiDocumenter.jl in the QED.jl project to compile all the documentation including the small documentation of QED.jl itself. If I'm not wrong, MultiDocumenter.jl requires to pull the rendered documentation of a package from a git repository. So the workflow for the CI would be:

1. build the Documenter.jl documentation of QED.jl
2. push the QED-jl documentation to a branch
3. run MultiDocumenter.jl, clone the QED.jl documentation again and render the doc
4. push the MultiDocumenter.jl documentation to the gh-branch

For a local builds, I can only image some workaround with a local git repository. Also using an extra repository for the MultiDocumenter.jl documentation is not ideal solution, because we want to use the URL of QED.jl project.

Is there any possibility to use the rendered documentation from a local build?

[pfitzseb]

Yeah, this is a bit confusing. You should be able to set upstream to some local directory and use an empty string (or any other value) for giturl.

[SimeonEhrig]

If I set giturl="" I get the following error:

┌ Error: Unable to update canonical URLs for this package
│   doc = MultiDocumenter.MultiDocRef("/home/simeon/projects/QED-project/QED.jl/docs/clones/QED", "QED", "QED.jl", true, "", "gh-pages")
│   exception =
│    MethodError: no method matching normpath(::Nothing)
│    
│    Closest candidates are:
│      normpath(::String)
│       @ Base path.jl:371
│      normpath(::AbstractString)
│       @ Base path.jl:595
│      normpath(::AbstractString, ::AbstractString...)
│       @ Base path.jl:411
│    
│    Stacktrace:
│      [1] update_canonical_links(docs_directory::String; canonical::String)
│        @ MultiDocumenter.DocumenterTools ~/.julia/packages/MultiDocumenter/ViaJG/src/documentertools/canonical_urls.jl:89
│      [2] update_canonical_links
│        @ ~/.julia/packages/MultiDocumenter/ViaJG/src/documentertools/canonical_urls.jl:81 [inlined]
│      [3] fix_canonical_url!(doc::MultiDocumenter.MultiDocRef; canonical::String, root_dir::String)
│        @ MultiDocumenter ~/.julia/packages/MultiDocumenter/ViaJG/src/canonical.jl:15
│      [4] fix_canonical_url!
│        @ ~/.julia/packages/MultiDocumenter/ViaJG/src/canonical.jl:3 [inlined]
│      [5] make_output_structure(docs::Vector{MultiDocumenter.MultiDocRef}, prettyurls::Bool, hide_previews::Bool; canonical::String)
│        @ MultiDocumenter ~/.julia/packages/MultiDocumenter/ViaJG/src/MultiDocumenter.jl:320
│      [6] make_output_structure
│        @ ~/.julia/packages/MultiDocumenter/ViaJG/src/MultiDocumenter.jl:296 [inlined]
│      [7] make(outdir::String, docs::Vector{MultiDocumenter.MultiDocRef}; assets_dir::Nothing, brand_image::Nothing, custom_stylesheets::Vector{Any}, custom_scripts::Vector{Any}, search_engine::MultiDocumenter.SearchConfig, prettyurls::Bool, rootpath::String, hide_previews::Bool, canonical_domain::String, sitemap::Bool, sitemap_filename::String, _override_windows_isinteractive_check::Bool)
│        @ MultiDocumenter ~/.julia/packages/MultiDocumenter/ViaJG/src/MultiDocumenter.jl:189
│      [8] top-level scope
│        @ ~/projects/QED-project/QED.jl/docs/multidocumenter.jl:119
│      [9] include(mod::Module, _path::String)
│        @ Base ./Base.jl:457
│     [10] exec_options(opts::Base.JLOptions)
│        @ Base ./client.jl:307
│     [11] _start()
│        @ Base ./client.jl:522
└ @ MultiDocumenter ~/.julia/packages/MultiDocumenter/ViaJG/src/canonical.jl:20

[pfitzseb]

I think that's an unrelated bug.

[SimeonEhrig]

But it looks like, that needs to be fix, that local builds works. Or am I wrong?

[pfitzseb]

Yeah, probably.

[kellertuer]

I at least get the same message if I try that in my repository as well, so I would be interested in a hint here as well. I mainly want to do a welcome page that explains the MultiDocumenter pages purpose

[kellertuer]

Ah! I think if you do

    MultiDocumenter.MultiDocRef(
        upstream = "build", # if docs build this is the default 
        path = "juliamanifolds", # where to put that in the final out folder
        name = "Home", # menu entry
        giturl = "", # something?
        branch = "", # maybe necessary not sure?
        fix_canonical_url = false, # this seems to fix the error from above, but since it is not documented I do not know what it does.
    )

at least my MultiDocumenter runs fine after running documenter (in the same make.jl)

[pfitzseb]

@mortenpi wanna fix the docs for this? :)

[kellertuer]

...so while the fix above seems to work locally (on Mac OS), I can not get it to work on CI, cf. https://github.com/JuliaManifolds/juliamanifolds.github.io/actions/runs/6786358771/job/18446707830#step:6:19, neither with leaving out the branch keyword nor with leaving out the giturl keyword.

edit: It seems one needs global directories, i.e.

 MultiDocumenter.MultiDocRef(
        upstream = joinpath(@__DIR__,"build"), # if docs build this is the default 
        path = "juliamanifolds", # where to put that in the final out folder
        name = "Home", # menu entry
        fix_canonical_url = false, # this seems to fix the error from above, but since it is not documented I do not know what it does.
    )

seems to work on both my machine and CI concerning the checks (that the folder exists so it does not try to pull/clone)