diff --git a/.travis.yml b/.travis.yml index 175e8a7a..9844fe8e 100644 --- a/.travis.yml +++ b/.travis.yml @@ -3,6 +3,7 @@ os: - linux services: - xvfb + - docker julia: - 1.3 - 1.4 diff --git a/Project.toml b/Project.toml index 00685bfc..6c8830a0 100644 --- a/Project.toml +++ b/Project.toml @@ -7,6 +7,7 @@ version = "0.3.3" [deps] AbstractTrees = "1520ce14-60c1-5f80-bbc7-55ef81b5835c" Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4" +DocumenterLaTeX = "cd674d7a-5f81-5cf3-af33-235ef1834b99" GitHub = "bc5e4493-9b4d-5f90-b8aa-2b2bcaad7a26" GithubMarkdown = "ecb7cac2-dae3-4a6f-a5f6-8274be99c6cb" Gumbo = "708ec375-b3d6-5a57-a7ce-8257bf98657a" @@ -21,6 +22,7 @@ UUIDs = "cf7118a7-6976-5b1a-9a39-7adc72f591a4" [compat] AbstractTrees = "0.2, 0.3" Documenter = "0.24" +DocumenterLaTeX = "0.2" GitHub = "5.1" GithubMarkdown = "0.1" Gumbo = "0.8" diff --git a/src/DocumentationGenerator.jl b/src/DocumentationGenerator.jl index ce8f37e7..732c3f29 100644 --- a/src/DocumentationGenerator.jl +++ b/src/DocumentationGenerator.jl @@ -36,7 +36,7 @@ function try_use_package(packagespec) return pkg_module end -function build_package_docs(packagespec::Pkg.Types.PackageSpec, buildpath, registry; src_prefix="", href_prefix="") +function build_package_docs(packagespec::Pkg.Types.PackageSpec, buildpath, registry; src_prefix="", href_prefix="", build_pdf=false) type, uri = doctype(packagespec, registry) @info("$(packagespec.name) specifies docs of type $(type).") @@ -44,9 +44,9 @@ function build_package_docs(packagespec::Pkg.Types.PackageSpec, buildpath, regis if type == "hosted" build_hosted_docs(packagespec, buildpath, uri) elseif type == "git-repo" - build_git_docs(packagespec, buildpath, uri; src_prefix=src_prefix, href_prefix=href_prefix) + build_git_docs(packagespec, buildpath, uri; src_prefix=src_prefix, href_prefix=href_prefix, build_pdf=build_pdf) elseif type == "vendored" - build_local_docs(packagespec, buildpath, uri; src_prefix=src_prefix, href_prefix=href_prefix) + build_local_docs(packagespec, buildpath, uri; src_prefix=src_prefix, href_prefix=href_prefix, build_pdf=build_pdf) else @error("Invalid doctype specified: $(type).") Dict( @@ -74,7 +74,8 @@ function build_documentation( sync_registry = true, deployment_url = "pkg.julialang.org/docs", update_only = false, - registry = joinpath(homedir(), ".julia/registries/General") + registry = joinpath(homedir(), ".julia/registries/General"), + build_pdf = false ) has_xvfb = try @@ -118,7 +119,8 @@ function build_documentation( juliacmd = juliacmd, registry_path = regpath, deployment_url = deployment_url, - update_only = update_only) + update_only = update_only, + build_pdf = build_pdf) push!(process_queue, proc) end end @@ -167,7 +169,7 @@ function get_pkg_eval_data() end function generate_dependency_list(packages; - basepath = joinpath(@__DIR__, ".."), + basepath = joinpath(@__DIR__, ".."), registry = joinpath(homedir(), ".julia/registries/General"), filter_versions = last ) @@ -210,7 +212,8 @@ function start_builder(package, version; deployment_url = error("`deployment_url` is a required argument."), update_only = error("`update_only` is a required argument."), src_prefix = nothing, - href_prefix = nothing + href_prefix = nothing, + build_pdf = false ) workerfile = joinpath(@__DIR__, "workerfile.jl") @@ -226,7 +229,7 @@ function start_builder(package, version; src_prefix = haskey(package, :src_prefix) ? package.src_prefix : string("/docs/", get_docs_dir(name, uuid), '/', string(version), "/_packagesource/") href_prefix = haskey(package, :href_prefix) ? package.href_prefix : string("/ui/Code/docs/", get_docs_dir(name, uuid), '/', string(version), "/_packagesource/") - builddir = joinpath(buildpath, get_docs_dir(name, uuid), string(version)) + builddir = build_pdf ? joinpath(buildpath, get_docs_dir(name, uuid), "pdf", string(version)) : joinpath(buildpath, get_docs_dir(name, uuid), string(version)) isdir(builddir) || mkpath(builddir) logfile = joinpath(builddir, "..", "$(version).log") @@ -249,6 +252,7 @@ function start_builder(package, version; $deployment_url $src_prefix $href_prefix + $build_pdf $(update_only ? "update" : "build") ``` diff --git a/src/builders.jl b/src/builders.jl index 1f21e428..fcef2e32 100644 --- a/src/builders.jl +++ b/src/builders.jl @@ -3,14 +3,14 @@ using GithubMarkdown using HTMLSanitizer using Highlights -function build_git_docs(packagespec, buildpath, uri; src_prefix="", href_prefix="") +function build_git_docs(packagespec, buildpath, uri; src_prefix="", href_prefix="", build_pdf=build_pdf) pkgname = packagespec.name return mktempdir() do dir return cd(dir) do run(`git clone --depth=1 $(uri) $(pkgname)`) docsproject = joinpath(dir, pkgname) return cd(docsproject) do - return build_local_docs(packagespec, buildpath, nothing, docsproject, gitdirdocs = true; src_prefix=src_prefix, href_prefix=href_prefix) + return build_local_docs(packagespec, buildpath, nothing, docsproject, gitdirdocs = true; src_prefix=src_prefix, href_prefix=href_prefix, build_pdf=build_pdf) end end end @@ -80,7 +80,7 @@ function maybe_redirect(uri) return uri end -function build_local_docs(packagespec, buildpath, uri, pkgroot = nothing; gitdirdocs = false, src_prefix="", href_prefix="") +function build_local_docs(packagespec, buildpath, uri, pkgroot = nothing; gitdirdocs = false, src_prefix="", href_prefix="", build_pdf=false) uri = something(uri, "docs") mktempdir() do envdir pkgname = packagespec.name @@ -106,7 +106,7 @@ function build_local_docs(packagespec, buildpath, uri, pkgroot = nothing; gitdir for docdir in joinpath.(pkgroot, unique([uri, "docs", "doc"])) if isdir(docdir) @info("Building vendored Documenter.jl documentation at $(docdir).") - output = build_documenter(packagespec, docdir) + output = build_documenter(packagespec, docdir, build_pdf) @info("Documentation built at $(output).") if output !== nothing @info("Copying build documentation from $(output) to $(buildpath)") @@ -115,7 +115,7 @@ function build_local_docs(packagespec, buildpath, uri, pkgroot = nothing; gitdir "doctype" => gitdirdocs ? "git-repo" : "documenter", "documenter_errored" => documenter_errored, "installable" => true, - "using_failed" => mod == nothing, + "using_failed" => mod === nothing, "success" => true ) else @@ -135,14 +135,14 @@ function build_local_docs(packagespec, buildpath, uri, pkgroot = nothing; gitdir # fallback docs (readme & docstrings) return mktempdir() do docsdir - output = build_readme_docs(pkgname, pkgroot, docsdir, mod, src_prefix, href_prefix) + output = build_readme_docs(pkgname, pkgroot, docsdir, mod, src_prefix, href_prefix, build_pdf) if output !== nothing cp(output, buildpath, force = true) return Dict( "doctype" => "fallback_autodocs", "documenter_errored" => documenter_errored, "installable" => true, - "using_failed" => mod == nothing, + "using_failed" => mod === nothing, "success" => true ) end @@ -150,14 +150,14 @@ function build_local_docs(packagespec, buildpath, uri, pkgroot = nothing; gitdir "doctype" => "fallback_autodocs", "documenter_errored" => documenter_errored, "installable" => true, - "using_failed" => mod == nothing, + "using_failed" => mod === nothing, "success" => false ) end end end -function build_legacy_documenter(packagespec, docdir) +function build_legacy_documenter(packagespec, docdir, build_pdf) open(joinpath(docdir, "Project.toml"), "w") do io println(io, """ [deps] @@ -167,16 +167,16 @@ function build_legacy_documenter(packagespec, docdir) Documenter = "~0.20" """) end - build_documenter(packagespec, docdir) + build_documenter(packagespec, docdir, build_pdf) end -function build_documenter(packagespec, docdir) +function build_documenter(packagespec, docdir, build_pdf) pkgdir = normpath(joinpath(docdir, "..")) cd(pkgdir) do docsproject = joinpath(docdir, "Project.toml") docsmanifest = joinpath(docdir, "Manifest.toml") if !isfile(docsproject) - return build_legacy_documenter(packagespec, docdir) + return build_legacy_documenter(packagespec, docdir, build_pdf) end # fix permissions to allow us to add the main pacakge to the docs project @@ -209,6 +209,7 @@ function build_documenter(packagespec, docdir) $(rundcocumenter) $(pkgdir) $(makefile) + $(build_pdf) ``` try @@ -222,7 +223,7 @@ function build_documenter(packagespec, docdir) end end -function build_readme_docs(pkgname, pkgroot, docsdir, mod, src_prefix, href_prefix) +function build_readme_docs(pkgname, pkgroot, docsdir, mod, src_prefix, href_prefix, build_pdf = false) @info("Generating readme-only fallback docs.") if pkgroot === nothing || !ispath(pkgroot) @@ -257,17 +258,34 @@ function build_readme_docs(pkgname, pkgroot, docsdir, mod, src_prefix, href_pref modules = :(Module[$mod]) end - @eval Module() begin - using Pkg - Pkg.add("Documenter") - using Documenter - makedocs( - format = Documenter.HTML(), - sitename = "$($pkgname).jl", - modules = $(modules), - root = $(docsdir), - pages = $(pages) - ) + if build_pdf + @eval Module() begin + using Pkg + Pkg.add("Documenter") + Pkg.add("DocumenterLaTeX") + using Documenter + using DocumenterLaTeX + makedocs( + format = LaTeX(platform = "docker"), + sitename = "$($pkgname).jl", + modules = $(modules), + root = $(docsdir), + pages = $(pages) + ) + end + else + @eval Module() begin + using Pkg + Pkg.add("Documenter") + using Documenter + makedocs( + format = Documenter.HTML(), + sitename = "$($pkgname).jl", + modules = $(modules), + root = $(docsdir), + pages = $(pages) + ) + end end build_dir = joinpath(docsdir, "build") diff --git a/src/rundocumenter.jl b/src/rundocumenter.jl index f8b3debd..e4c1a229 100644 --- a/src/rundocumenter.jl +++ b/src/rundocumenter.jl @@ -1,6 +1,9 @@ -if length(ARGS) == 2 +if length(ARGS) >= 2 pkgdir = ARGS[1] makefile = ARGS[2] + if length(ARGS) == 3 + build_pdf = ARGS[3] === "true" + end else makefile = joinpath(pwd(), "make.jl") pkgdir = normpath(joinpath(pwd(), "..")) @@ -38,7 +41,7 @@ end @info("Detected Documenter version $(documenter_version).") -expr, bpath = fix_makefile(makefile, documenter_version) +expr, bpath = fix_makefile(makefile, documenter_version, build_pdf) @info("`cd`ing to `$(docsdir)` and setting `tls[:SOURCE_PATH]` to `$(makefile)`.") diff --git a/src/utils/rewrite.jl b/src/utils/rewrite.jl index 3cb296fb..7dd4d7d2 100644 --- a/src/utils/rewrite.jl +++ b/src/utils/rewrite.jl @@ -24,7 +24,7 @@ Takes in the path to a Documenter.jl-compatible `make.jl` file and Return a tuple of `new_make_expr, buildpath`. """ -function fix_makefile(makefile, documenter_version = v"0.24") +function fix_makefile(makefile, documenter_version = v"0.24", is_pdf = false) # default output path: buildpath = joinpath(dirname(makefile), "build") should_break = false @@ -44,7 +44,11 @@ function fix_makefile(makefile, documenter_version = v"0.24") has_fmt = false has_sitename = false has_linkcheck = false - html = documenter_version < v"0.21" ? QuoteNode(:html) : :(Documenter.HTML()) + fmt = if is_pdf + :(LaTeX(platform = "docker")) + else + documenter_version < v"0.21" ? QuoteNode(:html) : :(Documenter.HTML()) + end fixkwarg = argument -> begin if Meta.isexpr(argument, :kw) @@ -52,10 +56,10 @@ function fix_makefile(makefile, documenter_version = v"0.24") # assure that we generate HTML if name == :format has_fmt = true - if Meta.isexpr(arg, :call) && arg.args[1] == :(Documenter.HTML) - append!(html.args, arg.args[2:end]) + if Meta.isexpr(arg, :call) && arg.args[1] == :(Documenter.HTML) && is_pdf + append!(fmt.args, arg.args[2:end]) end - argument.args[2] = html + argument.args[2] = fmt end # filter out root + build dir if name == :build @@ -92,7 +96,7 @@ function fix_makefile(makefile, documenter_version = v"0.24") if !has_fmt push!(new_args, Expr(:kw, :format, html)) end - + if !has_linkcheck push!(new_args, Expr(:kw, :linkcheck, false)) end @@ -112,6 +116,10 @@ function fix_makefile(makefile, documenter_version = v"0.24") fix_lnns(make_expr, makefile) + if is_pdf + pushfirst!(make_expr.args, :(using DocumenterLaTeX)) + end + return make_expr, buildpath end diff --git a/src/workerfile.jl b/src/workerfile.jl index 8c3b0520..d5496ca5 100644 --- a/src/workerfile.jl +++ b/src/workerfile.jl @@ -4,7 +4,8 @@ using DocumentationGenerator Pkg.status() -function build(uuid, name, url, version, buildpath, registry, deployment_url, src_prefix, href_prefix, args...) +function build(uuid, name, url, version, buildpath, registry, deployment_url, src_prefix, href_prefix, build_pdf, args...) + build_pdf = build_pdf == "true" packagespec = PackageSpec(uuid = uuid, name = name, version = VersionNumber(version)) withenv( "DOCUMENTATIONGENERATOR" => "true", @@ -12,8 +13,12 @@ function build(uuid, name, url, version, buildpath, registry, deployment_url, sr "DOCUMENTATIONGENERATOR_BASE_URL" => DocumentationGenerator.docs_url(deployment_url, name, uuid, version) ) do metadata = DocumentationGenerator.package_metadata(packagespec, url) - build_meta = DocumentationGenerator.build_package_docs(packagespec, buildpath, registry; src_prefix=src_prefix, href_prefix=href_prefix) - merge!(metadata, build_meta) + build_meta = DocumentationGenerator.build_package_docs(packagespec, buildpath, registry; src_prefix=src_prefix, href_prefix=href_prefix, build_pdf=build_pdf) + if build_pdf + merge!(metadata, Dict("pdf" => build_meta)) + else + merge!(metadata, build_meta) + end isdir(buildpath) || mkpath(buildpath) diff --git a/test/runtests.jl b/test/runtests.jl index 0cd49595..7d6c93ef 100644 --- a/test/runtests.jl +++ b/test/runtests.jl @@ -252,6 +252,10 @@ end packages, basepath = basepath, filter_versions = identity, processes = 1 ) + DocumentationGenerator.build_documentation( + [packages[end]], basepath = basepath, filter_versions = identity, processes = 1, build_pdf = true + ) + build = joinpath(basepath, "build") @testset "build folder" begin for pkg in packages @@ -308,6 +312,13 @@ end @test occursin("""""", readme) @test occursin("""

Installation

""", readme) end + + if pkg == packages[end] + @testset "pdf generation" begin + @test isfile(joinpath(pkgbuild, "pdf", string(version), string(pkg.name, ".jl", ".pdf"))) + @test isfile(joinpath(pkgbuild, "pdf", string(version, ".log"))) + end + end end end end @@ -330,4 +341,4 @@ end @test DocumentationGenerator.github_to_raw("https://raw.githubusercontent.com/migarstka/COSMO_assets/master/COSMO_logo_only.png") == "https://raw.githubusercontent.com/migarstka/COSMO_assets/master/COSMO_logo_only.png" @test DocumentationGenerator.github_to_raw("https://www.github.com/migarstka/COSMO_assets/blob/master/COSMO_logo_only.png") == "https://raw.githubusercontent.com/migarstka/COSMO_assets/master/COSMO_logo_only.png" @test DocumentationGenerator.github_to_raw("https://github.com/migarstka/COSMO_assets/master/COSMO_logo_only.png") == "https://github.com/migarstka/COSMO_assets/master/COSMO_logo_only.png" -end \ No newline at end of file +end