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.

Exports

• Deps
• DocMeta
• deploydocs
• doctest
• hide
• makedocs

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

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 = joinpath(dirname(pathof(MyModule)), "..", "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.

Setting doctest to :only allows for doctesting without a full build. In this mode, most build stages are skipped and the strict keyword is ignore (a doctesting error will always make makedocs throw an error).

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 branch or tag name, or commit hash
• {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}#{line}")

highlightsig enables or disables automatic syntax highlighting of leading, unlabeled code blocks in docstrings (as Julia code). For example, if your docstring begins with an indented code block containing the function signature, then that block would be highlighted as if it were a labeled Julia code block. No other code blocks are affected. This feature is enabled by default.

sitename is displayed in the title bar and/or the navigation menu when applicable.

expandfirst allows some of the pages to be expanded (i.e. at-blocks evaluated etc.) before the others. Documenter normally evaluates the files in the alphabetic order of their file paths relative to src, but expandfirst allows some pages to be prioritized.

For example, if you have foo.md and bar.md, bar.md would normally be evaluated before foo.md. But with expandfirst = ["foo.md"], you can force foo.md to be evaluated first.

Evaluation order among the expandfirst pages is according to the order they appear in the argument.

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.

workdir determines the working directory where @example and @repl code blocks are executed. It can be either a path or the special value :build (default).

If the workdir is set to a path, the working directory is reset to that path for each code block being evaluated. Relative paths are taken to be relative to root, but using absolute paths is recommended (e.g. workdir = joinpath(@__DIR__, "..") for executing in the package root for the usual docs/make.jl setup).

With the default :build option, the working directory is set to a subdirectory of build, determined from the source file path. E.g. for src/foo.md it is set to build/, for src/foo/bar.md it is set to build/foo etc.

Note that workdir does not affect doctests.

Output formats

format allows the output format to be specified. The default format is Documenter.HTML which creates a set of HTML files.

There are other possible formats that are enabled by using other addon-packages. For examples, the DocumenterMarkdown package define the DocumenterMarkdown.Markdown() format for use with e.g. MkDocs, and the DocumenterLaTeX package define the DocumenterLaTeX.LaTeX() format for LaTeX / PDF output. See the Other Output Formats for more information.

See Also

A guide detailing how to document a package using Documenter's makedocs is provided in the setup guide in 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 = "build",
    repo   = "<required>",
    branch = "gh-pages",
    deps   = nothing | <Function>,
    make   = nothing | <Function>,
    devbranch = "master",
    devurl = "dev",
    versions = ["stable" => "v^", "v#.#", devurl => devurl]
)

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/..."
)

When building the docs for a tag (i.e. a release) the documentation is deployed to a directory with the tag name (i.e. vX.Y.Z) and to the stable directory. Otherwise the docs are deployed to the directory determined by the devurl argument.

Required keyword arguments

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"

Optional keyword arguments

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

target is the directory, relative to root, where generated content that should be deployed to gh-pages is written to. written to. It should generally be the same as makedocs's build and defaults to "build".

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".

deps is the function used to install any additional dependencies needed to build the documentation. By default nothing is installed.

It can be used e.g. for a Markdown build. The following example installed the pygments and mkdocs Python packages using the Deps.pip function:

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

make is the function used to specify an additonal build phase. By default, nothing gets executed.

devbranch is the branch that "tracks" the in-development version of the generated documentation. By default this value is set to "master".

devurl the folder that in-development version of the docs will be deployed. Defaults to "dev".

forcepush a boolean that specifies the behavior of the git-deployment. The default (forcepush = false) is to push a new commit, but when forcepush = true the changes will be combined with the previous commit and force pushed, erasing the Git history on the deployment branch.

versions determines content and order of the resulting version selector in the generated html. The following entries are valied in the versions vector:

• "v#": includes links to the latest documentation for each major release cycle (i.e. v2.0, v1.1).
• "v#.#": includes links to the latest documentation for each minor release cycle (i.e. v2.0, v1.1, v1.0, v0.1).
• "v#.#.#": includes links to all released versions.
• "v^": includes a link to the docs for the maximum version (i.e. a link vX.Y pointing to vX.Y.Z for highest X, Y, Z, respectively).
• A pair, e.g. "first" => "second", which will put "first" in the selector, and generate a url from which "second" can be accessed. The second argument can be "v^", to point to the maximum version docs (as in e.g. "stable" => "v^").

Environment variables

deploydocs's behavior is influenced by the following environment variables, many of which are specific to the Travis CI platform.

• DOCUMENTER_KEY: must contain the Base64-encoded SSH private key for the repository.

• TRAVIS_PULL_REQUEST: must be set to false.

  This avoids deployment on pull request builds. Note that there is no way to safely enable builds on pull requests, since that would expose the SSH private key (DOCUMENTER_KEY), giving anyone opening a pull request full write access to the repository.

• TRAVIS_REPO_SLUG: must match the value of the repo keyword.

• TRAVIS_EVENT_TYPE: may not be set to cron.

  This avoids the re-deployment of existing docs on builds that were triggered by a Travis cron job.

• TRAVIS_BRANCH: unless TRAVIS_TAG is non-empty, this must have the same value as the devbranch keyword.

  This makes sure that only the development branch (commonly, the master branch) will deploy the "dev" documentation (deployed into a directory specified by the devurl keyword).

• TRAVIS_TAG: if set, a tagged version deployment is performed instead; the value must be a valid version number (i.e. match Base.VERSION_REGEX).

  The documentation for a package version tag gets deployed to a directory named after the version number in TRAVIS_TAG instead.

The TRAVIS_* variables are set automatically on Travis, but could be set manually to appropriate values as well to run deploydocs locally or on other CI platforms. More information on how Travis sets the TRAVIS_* variables can be found in the Travis documentation.

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 them to GitHub.

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"),
    # ...
)

doctest(package::Module; kwargs...)

Convenience method that runs and checks all the doctests for a given Julia package. package must be the Module object corresponding to the top-level module of the package. Behaves like an @testset call, returning a testset if all the doctests are successful or throwing a TestSetException if there are any failures. Can be included in other testsets.

Keywords

manual controls how manual pages are handled. By default (manual = true), doctest assumes that manual pages are located under docs/src. If that is not the case, the manual keyword argument can be passed to specify the directory. Setting manual = false will skip doctesting of manual pages altogether.

Additional keywords are passed on to the main doctest method.

doctest(source, modules; kwargs...)

Runs all the doctests in the given modules and on manual pages under the source directory. Behaves like an @testset call, returning a testset if all the doctests are successful or throwing a TestSetException if there are any failures. Can be included in other testsets.

The manual pages are searched recursively in subdirectories of source too. Doctesting of manual pages can be disabled if source is set to nothing.

Keywords

testset specifies the name of test testset (default Doctests).

fix, if set to true, updates all the doctests that fail with the correct output (default false).

This module provides APIs for handling documentation metadata in modules.

The implementation is similar to how docstrings are handled in Base by the Base.Docs module — a special variable is created in each module that has documentation metadata.

Public API

• DocMeta.getdocmeta
• DocMeta.setdocmeta!

Supported metadata

• DocTestSetup: contains the doctest setup code for doctests in the module.

getdocmeta(m::Module)

Returns the documentation metadata dictionary for the module m. The dictionary should be considered immutable and assigning values to it is not well-defined. To set documentation metadata values, DocMeta.setdocmeta! should be used instead.

getdocmeta(m::Module, key::Symbol, default=nothing)

Return the key entry from the documentation metadata for module m, or default if the value is unset.

setdocmeta!(m::Module, key::Symbol, value; recursive=false, warn=true)

Set the documentation metadata value key for module m to value.

If recursive is set to true, it sets the same metadata value for all the submodules too. If warn is true, it prints a warning when key already exists and is gets rewritten.

DocumenterTools.generate(path::String = "docs"; name = nothing, format = :html)

Create a documentation stub in path, which is usually a sub folder in the package root. The name of the package is determined automatically, but can be given with the name keyword argument.

generate can also be called without any arguments, in which case it simply puts all the generated files into a docs directory in the current working directory. This way, if you are already in the root directory of your package, you generally only need to call generate() to generate the documentation stub.

generate creates the following files in path:

.gitignore
src/index.md
make.jl
mkdocs.yml
Project.toml

Arguments

path file path to the documentation directory to be created (default is "docs").

Keywords Arguments

name is the name of the package (without .jl). If name is not given generate tries to detect it automatically.

format can be either :html (default), :markdown or :pdf corresponding to the format keyword to Documenter's makedocs function, see Documenter's manual.

Examples

julia> using DocumenterTools

julia> DocumenterTools.generate("path/to/MyPackage/docs")
[ ... output ... ]

DocumenterTools.generate(pkg::Module; dir = "docs", format = :html)

Same as generate(path::String) but the path and name is determined automatically from the module.

Examples

julia> using DocumenterTools

julia> using MyPackage

julia> DocumenterTools.generate(MyPackage)
[ ... output ... ]

genkeys(; user="$USER", repo="$REPO")

Generates the SSH keys necessary for the automatic deployment of documentation with Documenter from Travis to GitHub Pages.

By default the links in the instructions need to be modified to correspond to actual URLs. The optional user and repo keyword arguments can be specified so that the URLs in the printed instructions could be copied directly. They should be the name of the GitHub user or organization where the repository is hosted and the full name of the repository, respectively.

This method of genkeys requires the following command lines programs to be installed:

• which
• ssh-keygen

Examples

julia> using DocumenterTools

julia> Travis.genkeys()
[ Info: add the public key below to https://github.com/$USER/$REPO/settings/keys with read/write access:

ssh-rsa AAAAB3NzaC2yc2EAAAaDAQABAAABAQDrNsUZYBWJtXYUk21wxZbX3KxcH8EqzR3ZdTna0Wgk...jNmUiGEMKrr0aqQMZEL2BG7 username@hostname

[ Info: add a secure environment variable named 'DOCUMENTER_KEY' to https://travis-ci.com/$USER/$REPO/settings with value:

LS0tLS1CRUdJTiBSU0EgUFJJVkFURSBLRVktLS0tLQpNSUlFb3dJQkFBS0NBUUVBNnpiRkdXQVZpYlIy...QkVBRWFjY3BxaW9uNjFLaVdOcDU5T2YrUkdmCi0tLS0tRU5EIFJTQSBQUklWQVRFIEtFWS0tLS0tCg==


julia> Travis.genkeys(user="JuliaDocs", repo="DocumenterTools.jl")
[Info: add the public key below to https://github.com/JuliaDocs/DocumenterTools.jl/settings/keys with read/write access:

ssh-rsa AAAAB3NzaC2yc2EAAAaDAQABAAABAQDrNsUZYBWJtXYUk21wxZbX3KxcH8EqzR3ZdTna0Wgk...jNmUiGEMKrr0aqQMZEL2BG7 username@hostname

[ Info: add a secure environment variable named 'DOCUMENTER_KEY' to https://travis-ci.com/JuliaDocs/DocumenterTools.jl/settings with value:

LS0tLS1CRUdJTiBSU0EgUFJJVkFURSBLRVktLS0tLQpNSUlFb3dJQkFBS0NBUUVBNnpiRkdXQVZpYlIy...QkVBRWFjY3BxaW9uNjFLaVdOcDU5T2YrUkdmCi0tLS0tRU5EIFJTQSBQUklWQVRFIEtFWS0tLS0tCg==

genkeys(package::Module; remote="origin")

Like the other method, this generates the SSH keys necessary for the automatic deployment of documentation with Documenter from Travis to GitHub Pages, but attempts to guess the package URLs from the Git remote.

package needs to be the top level module of the package. The remote keyword argument can be used to specify which Git remote is used for guessing the repository's GitHub URL.

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

• which
• git
• ssh-keygen

Examples

julia> using DocumenterTools

julia> Travis.genkeys(DocumenterTools)
[Info: add the public key below to https://github.com/JuliaDocs/DocumenterTools.jl/settings/keys with read/write access:

ssh-rsa AAAAB3NzaC2yc2EAAAaDAQABAAABAQDrNsUZYBWJtXYUk21wxZbX3KxcH8EqzR3ZdTna0Wgk...jNmUiGEMKrr0aqQMZEL2BG7 username@hostname

[ Info: add a secure environment variable named 'DOCUMENTER_KEY' to https://travis-ci.com/JuliaDocs/DocumenterTools.jl/settings with value:

LS0tLS1CRUdJTiBSU0EgUFJJVkFURSBLRVktLS0tLQpNSUlFb3dJQkFBS0NBUUVBNnpiRkdXQVZpYlIy...QkVBRWFjY3BxaW9uNjFLaVdOcDU5T2YrUkdmCi0tLS0tRU5EIFJTQSBQUklWQVRFIEtFWS0tLS0tCg==

Package functions for interacting with Travis.

• genkeys