How can I find the reason why docs aren't deployed?

bicycle1885 · January 13, 2017, 2:10am

Hi,

I’m now working on a new package Automa.jl and struggling to deploy docs on GitHub pages using Documenter.jl. I read the manual of Documenter.jl and I believe it was properly configured. However, all TravisCI build jobs skip the deployment of its docs. Here is the latest build on Travis CI: Travis CI - Test and Deploy Your Code with Confidence. I think, by default, Documenter.jl will choose Linux OS on the nightly build for deployment but the build log says it is skipped. I have no clue to diagnose the reason why this happens here. Docs deployment works properly on other my packages.

tshort · January 13, 2017, 2:47am

You can set an environment variable in your travis.yml file to give information on why deployment didn’t trigger. Here’s an example:

github.com

tshort/ReactiveBasics.jl/blob/master/.travis.yml#L17


      
            - 1.4.0
            - 1
            - nightly
          notifications:
            email: false
          # uncomment the following lines to override the default test script
          #script:
          #  - if [[ -a .git/shallow ]]; then git fetch --unshallow; fi
          #  - julia -e 'Pkg.clone(pwd()); Pkg.build("ReactiveBasics"); Pkg.test("ReactiveBasics"; coverage=true)'
          after_success:
            - julia -e 'Pkg.add("Documenter")'
            - julia -e 'ENV["DOCUMENTER_DEBUG"] = "true"; cd(Pkg.dir("ReactiveBasics", "docs")); include("make.jl")'
            # push coverage results to Coveralls
            - julia -e 'cd(Pkg.dir("ReactiveBasics")); Pkg.add("Coverage"); using Coverage; Coveralls.submit(Coveralls.process_folder())'
            # push coverage results to Codecov
            - julia -e 'cd(Pkg.dir("ReactiveBasics")); Pkg.add("Coverage"); using Coverage; Codecov.submit(Codecov.process_folder())'

Here’s an example where that successfully deployed:

Here is the logic for deployment:

github.com

JuliaDocs/Documenter.jl/blob/master/src/Documenter.jl#L328


      
          """
          Main module for `Documenter.jl` -- a documentation generation package for Julia.
          
          Two functions are exported from this module for public use:
          
          - [`makedocs`](@ref). Generates documentation from docstrings and templated markdown files.
          - [`deploydocs`](@ref). Deploys generated documentation from *Travis-CI* to *GitHub Pages*.
          
          # Exports
          
          $(EXPORTS)
          
          """
          module Documenter
          
          import AbstractTrees
          import Downloads
          import IOCapture
          import Markdown
          using MarkdownAST: MarkdownAST, Node
          import REPL
          import Unicode
          import Pkg
          import RegistryInstances
          # Additional imported names
          using Test: @testset, @test
          using DocStringExtensions
          using Base64: base64decode
          
          # Version number of Documenter itself
          const DOCUMENTER_VERSION = let
              project = joinpath(dirname(dirname(pathof(Documenter))), "Project.toml")
              Base.include_dependency(project) # Retrigger precompilation when Project.toml changes
              toml = read(project, String)
              m = match(r"(*ANYCRLF)^version\s*=\s\"(.*)\"$"m, toml)
              VersionNumber(m[1])
          end
          
          # Potentially sensitive variables to be removed from environment when not needed
          const NO_KEY_ENV = Dict(
              "DOCUMENTER_KEY" => nothing,
              "DOCUMENTER_KEY_PREVIEWS" => nothing,
          )
          
          # Names of possible internal errors
          const ERROR_NAMES = [:autodocs_block, :cross_references, :docs_block, :doctest,
                               :eval_block, :example_block, :footnote, :linkcheck_remotes, :linkcheck,
                               :meta_block, :missing_docs, :parse_error, :setup_block]
          
          """
              abstract type Plugin end
          
          Any plugin that needs to either solicit user input or store information in a
          [`Document`](@ref) should create a subtype of `Plugin`, i.e., `T <: DocumenterPlugin`.
          
          Initialized objects of type `T` can be elements of the list of `plugins` passed as a
          keyword argument to [`makedocs`](@ref).
          
          A plugin may retrieve the existing object holding its state via the
          [`Documenter.getplugin`](@ref) function. Alternatively, `getplugin` can also instantiate
          `T()` on demand, if there is no existing object. This requires that `T` implements an empty
          constructor `T()`.
          """
          abstract type Plugin end
          
          abstract type Writer end
          
          include("utilities/DOM.jl")
          include("utilities/JSDependencies.jl")
          include("utilities/MDFlatten.jl")
          include("utilities/Remotes.jl")
          include("utilities/Selectors.jl")
          include("utilities/TextDiff.jl")
          include("utilities/utilities.jl")
          include("DocMeta.jl")
          include("DocSystem.jl")
          include("anchors.jl")
          include("documents.jl")
          include("expander_pipeline.jl")
          include("doctests.jl")
          include("builder_pipeline.jl")
          include("cross_references.jl")
          include("docchecks.jl")
          include("writers.jl")
          include("html/HTMLWriter.jl")
          include("latex/LaTeXWriter.jl")
          
          # This is to keep DocumenterTools working:
          module Writers
          import ..HTMLWriter
          end
          
          import .HTMLWriter: HTML, asset
          import .HTMLWriter.RD: KaTeX, MathJax, MathJax2, MathJax3
          import .LaTeXWriter: LaTeX
          
          # User Interface.
          # ---------------
          export makedocs, deploydocs, hide, doctest, DocMeta, asset, Remotes,
              KaTeX, MathJax, MathJax2, MathJax3
          
          include("makedocs.jl")
          include("deployconfig.jl")
          include("deploydocs.jl")
          include("doctest.jl")
          
          import PrecompileTools
          PrecompileTools.@compile_workload begin
              include("docs_precompile/make.jl")
          end
          
          end # module

bicycle1885 · January 13, 2017, 3:21am

Thank you! Really helpful information.

Balinus · January 13, 2017, 1:58pm

I took a look and it seems resolved right?

bicycle1885 · January 13, 2017, 2:09pm

Yes, this and this solved my problem.

Balinus · January 13, 2017, 2:10pm

Thanks. That’s what I thought.

I had a similar problem a couple of weeks before.