Public Documentation

Main module for Documenter.jl – a documentation generation package for Julia.

Two functions are exported from this module for public use:

• makedocs. Generates documentation from docstrings and templated markdown files.

• deploydocs. Deploys generated documentation from Travis-CI to GitHub Pages.

Additionally it provides the unexported Documenter.generate, which can be used to generate documentation stubs for new packages.

• Deps

• Travis

• deploydocs

• hide

• makedocs

makedocs(
    root    = "<current-directory>",
    source  = "src",
    build   = "build",
    clean   = true,
    doctest = true,
    modules = Module[],
    repo    = "",
)

Combines markdown files and inline docstrings into an interlinked document. In most cases makedocs should be run from a make.jl file:

using Documenter
makedocs(
    # keywords...
)

which is then run from the command line with:

$ julia make.jl

The folder structure that makedocs expects looks like:

docs/
    build/
    src/
    make.jl

Keywords

root is the directory from which makedocs should run. When run from a make.jl file this keyword does not need to be set. It is, for the most part, needed when repeatedly running makedocs from the Julia REPL like so:

julia> makedocs(root = Pkg.dir("MyPackage", "docs"))

source is the directory, relative to root, where the markdown source files are read from. By convention this folder is called src. Note that any non-markdown files stored in source are copied over to the build directory when makedocs is run.

build is the directory, relative to root, into which generated files and folders are written when makedocs is run. The name of the build directory is, by convention, called build, though, like with source, users are free to change this to anything else to better suit their project needs.

clean tells makedocs whether to remove all the content from the build folder prior to generating new content from source. By default this is set to true.

doctest instructs makedocs on whether to try to test Julia code blocks that are encountered in the generated document. By default this keyword is set to true. Doctesting should only ever be disabled when initially setting up a newly developed package where the developer is just trying to get their package and documentation structure correct. After that, it's encouraged to always make sure that documentation examples are runnable and produce the expected results. See the Doctests manual section for details about running doctests.

modules specifies a vector of modules that should be documented in source. If any inline docstrings from those modules are seen to be missing from the generated content then a warning will be printed during execution of makedocs. By default no modules are passed to modules and so no warnings will appear. This setting can be used as an indicator of the "coverage" of the generated documentation. For example Documenter's make.jl file contains:

makedocs(
    modules = [Documenter],
    # ...
)

and so any docstring from the module Documenter that is not spliced into the generated documentation in build will raise a warning.

repo specifies a template for the "link to source" feature. If you are using GitHub, this is automatically generated from the remote. If you are using a different host, you can use this option to tell Documenter how URLs should be generated. The following placeholders will be replaced with the respective value of the generated link:

• {commit} Git commit id

• {path} Path to the file in the repository

• {line} Line (or range of lines) in the source file

For example if you are using GitLab.com, you could use

makedocs(repo = "https://gitlab.com/user/project/blob/{commit}{path}#L{line}")

Experimental keywords

In addition to standard arguments there is a set of non-finalized experimental keyword arguments. The behaviour of these may change or they may be removed without deprecation when a minor version changes (i.e. except in patch releases).

checkdocs instructs makedocs to check whether all names within the modules defined in the modules keyword that have a docstring attached have the docstring also listed in the manual (e.g. there's a @docs blocks with that docstring). Possible values are :all (check all names) and :exports (check only exported names). The default value is :none, in which case no checks are performed. If strict is also enabled then the build will fail if any missing docstrings are encountered.

linkcheck – if set to truemakedocs uses curl to check the status codes of external-pointing links, to make sure that they are up-to-date. The links and their status codes are printed to the standard output. If strict is also enabled then the build will fail if there are any broken (400+ status code) links. Default: false.

linkcheck_ignore allows certain URLs to be ignored in linkcheck. The values should be a list of strings (which get matched exactly) or Regex objects. By default nothing is ignored.

strict – makedocs fails the build right before rendering if it encountered any errors with the document in the previous build phases.

Non-MkDocs builds

Documenter also has (experimental) support for native HTML and LaTeX builds. These can be enabled using the format keyword and they generally require additional keywords be defined, depending on the format. These keywords are also currently considered experimental.

format allows the output format to be specified. Possible values are :html, :latex and :markdown (default).

Other keywords related to non-MkDocs builds (assets, sitename, analytics, authors, pages, version) should be documented at the respective *Writer modules (Writers.HTMLWriter, Writers.LaTeXWriter).

See Also

A guide detailing how to document a package using Documenter's makedocs is provided in the Usage section of the manual.

hide(page)

Allows a page to be hidden in the navigation menu. It will only show up if it happens to be the current page. The hidden page will still be present in the linear page list that can be accessed via the previous and next page links. The title of the hidden page can be overriden using the => operator as usual.

Usage

makedocs(
    ...,
    pages = [
        ...,
        hide("page1.md"),
        hide("Title" => "page2.md")
    ]
)

hide(root, children)

Allows a subsection of pages to be hidden from the navigation menu. root will be linked to in the navigation menu, with the title determined as usual. children should be a list of pages (note that it can not be hierarchical).

Usage

makedocs(
    ...,
    pages = [
        ...,
        hide("Hidden section" => "hidden_index.md", [
            "hidden1.md",
            "Hidden 2" => "hidden2.md"
        ]),
        hide("hidden_index.md", [...])
    ]
)

deploydocs(
    root   = "<current-directory>",
    target = "site",
    repo   = "<required>",
    branch = "gh-pages",
    latest = "master",
    osname = "linux",
    julia  = "nightly",
    deps   = <Function>,
    make   = <Function>,
)

Converts markdown files generated by makedocs to HTML and pushes them to repo. This function should be called from within a package's docs/make.jl file after the call to makedocs, like so

using Documenter, PACKAGE_NAME
makedocs(
    # options...
)
deploydocs(
    repo = "github.com/..."
)

Keywords

root has the same purpose as the root keyword for makedocs.

target is the directory, relative to root, where generated HTML content should be written to. This directory must be added to the repository's .gitignore file. The default value is "site".

repo is the remote repository where generated HTML content should be pushed to. Do not specify any protocol - "https://" or "git@" should not be present. This keyword must be set and will throw an error when left undefined. For example this package uses the following repo value:

repo = "github.com/JuliaDocs/Documenter.jl.git"

branch is the branch where the generated documentation is pushed. If the branch does not exist, a new orphaned branch is created automatically. It defaults to "gh-pages".

latest is the branch that "tracks" the latest generated documentation. By default this value is set to "master".

osname is the operating system which will be used to deploy generated documentation. This defaults to "linux". This value must be one of those specified in the os: section of the .travis.yml configuration file.

julia is the version of Julia that will be used to deploy generated documentation. This defaults to "nightly". This value must be one of those specified in the julia: section of the .travis.yml configuration file.

deps is the function used to install any dependencies needed to build the documentation. By default this function installs pygments and mkdocs using the Deps.pip function:

deps = Deps.pip("pygments", "mkdocs")

make is the function used to convert the markdown files to HTML. By default this just runs mkdocs build which populates the target directory.

See Also

The Hosting Documentation section of the manual provides a step-by-step guide to using the deploydocs function to automatically generate docs and push then to GitHub.

generate(pkgname; dir)

Creates a documentation stub for a package called pkgname. The location of the documentation is assumed to be <package directory>/docs, but this can be overriden with the keyword argument dir.

It creates the following files

docs/
    .gitignore
    src/index.md
    make.jl
    mkdocs.yml

Arguments

pkgname is the name of the package (without .jl). It is used to determine the location of the documentation if dir is not provided.

Keywords

dir defines the directory where the documentation will be generated. It defaults to <package directory>/docs. The directory must not exist.

Examples

julia> using Documenter

julia> Documenter.generate("MyPackageName")
[ ... output ... ]

Package functions for interacting with Travis.

• genkeys

genkeys(package; remote)

Generate ssh keys for package package to automatically deploy docs from Travis to GitHub pages. package can be either the name of a package or a path. Providing a path allows keys to be generated for non-packages or packages that are not found in the Julia LOAD_PATH. Use the remote keyword to specify the user and repository values.

This function requires the following command lines programs to be installed:

• which

• git

• travis

• ssh-keygen

Examples

julia> using Documenter

julia> Travis.genkeys("MyPackageName")
[ ... output ... ]

julia> Travis.genkeys("MyPackageName", remote="organization")
[ ... output ... ]

julia> Travis.genkeys("/path/to/target/directory")
[ ... output ... ]

Exported module that provides build and deploy dependencies and related functions.

Currently only pip is implemented.

pip(deps)

Installs (as non-root user) all python packages listed in deps.

Examples

using Documenter

makedocs(
    # ...
)

deploydocs(
    deps = Deps.pip("pygments", "mkdocs", "mkdocs-material"),
    # ...
)