Deploy Documenter docs locally

General Usage
, ,
1

As I understand it, the function deploydocs in Documenter.jl is designed to work with travis only. I have a private repository I would like to generate documentation for, and would like a deploydocs function that could deploy my generated documentation when run on my local machine. Anyone having accomplished this before and have some insight/experiences on a nice approach?

2

If you’re using MkDocs (the default, instead of native HTML), you can simply run the following in the docs directory:

julia make.jl
mkdocs serve

This is assuming you have MkDocs installed, as well as any Python packages you’ve listed in your deploydocs call. Actually, you can keep the server running and only run julia make.jl, as the server will detect the changes and auto-reload and refresh your browser.

If you’re using native HTML, simply open the generated HTML files.

3

Thanks! That seems to be working well.
I would also be interested in automatic deployment to a git branch, e.g., gh-pages as deploydocs does.

4

I created a short julia script to set the environment variables the way travis would set them. Need to keep this outside the repository since it contains the deploy key.

ENV["TRAVIS_REPO_SLUG"] = "github.com/cstook/LTspice.jl.git"
ENV["TRAVIS_PULL_REQUEST"] = "false"
ENV["TRAVIS_OS_NAME"] = "linux"
ENV["TRAVIS_JULIA_VERSION"] = "0.6"
ENV["TRAVIS_TAG"] = "master"
ENV["DOCUMENTER_KEY"] = key not shown

Then modify the make.jl file to include this script is it exists.

if "deploy" in ARGS
  fake_travis = "C:/Users/Chris/fake_travis_LTspice.jl"
  if isfile(fake_travis)
    include(fake_travis)
  end
  deploydocs(
    repo = "github.com/cstook/LTspice.jl.git",
    target = "site",
    branch = "gh-pages",
    latest = "master",
    osname = "linux",
    julia  = "0.6",
    deps = nothing,
    make = nothing,
  )
end
1 Like
5

Haven’t tried this, but in theory mkdocs gh-deploy should work.

7

@cstook Many thanks for this! I found I had to make a few changes, presumably because Documenter has changed in the meantime:

# contents of faketravis.jl
ENV["TRAVIS_REPO_SLUG"] = "github.com/USER_NAME/PROJECT_NAME.jl.git"
ENV["TRAVIS_PULL_REQUEST"] = "false"
ENV["TRAVIS_OS_NAME"] = "macos" # or "linux"
ENV["TRAVIS_JULIA_VERSION"] = "1.1"
ENV["TRAVIS_TAG"] = ""
ENV["TRAVIS_BRANCH"] = "master"
ENV["DOCUMENTER_KEY"] = "..."  # insert private key and add public key to Github project

and in make.jl:

if "deploy" in ARGS
  include("../../faketravis.jl")
end

deploydocs(deps = nothing, make = nothing,
  repo = "github.com/USER_NAME/PROJECT_NAME.jl.git",
  target = "build",
  branch = "gh-pages",
  devbranch = "master",
)

Issuing julia make.jl deploy builds and deploys the docs. Perfect for projects that depend on proprietary software.