Public

Public Documentation

Documentation for Documenter.jl's public interface.

See Internal Documentation for internal package docs covering all submodules.

Contents

Index

Public Interface

DocumenterModule.

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

source
Documenter.makedocsFunction.
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 = joinpath(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.

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}")

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 true makedocs 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.

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

Output formats

format allows the output format to be specified. The default value is :html. Other formats can be enabled by using other packages. For examples, see the DocumenterMarkdown and DocumenterLaTeX packages.

Documenter is designed to support multiple output formats. By default it is creates a set of HTML files, but the output format can be controlled with the format keyword. The different output formats may require additional keywords to be specified via plugins. The keywords for the default HTML output are documented for the Writers.HTMLWriter.HTML type.

The default :html output format creates a set of HTML files, but Documenter is designed to support multiple output formats. Via plugin packages, Documenter also supports e.g. Markdown / MkDocs and LaTeX / PDF outputs. 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.

source
Documenter.hideFunction.
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")
    ]
)
source
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", [...])
    ]
)
source
Documenter.deploydocsFunction.
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".

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

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.

source
Documenter.DepsModule.

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

Currently only pip is implemented.

source
Documenter.Deps.pipFunction.
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"),
    # ...
)
source

DocumenterTools

DocumenterTools.generate(path::String; 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 creates the following files in path:

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

Arguments

path file path to the documentation directory.

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

Note

The package must be in development mode. Make sure you run pkg> develop pkg from the Pkg REPL, or Pkg.develop("pkg") before generating docs.

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.org/$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.org/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
Note

The package must be in development mode. Make sure you run pkg> develop pkg from the Pkg REPL, or Pkg.develop("pkg") before generating the SSH keys.

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.org/JuliaDocs/DocumenterTools.jl/settings with value:

LS0tLS1CRUdJTiBSU0EgUFJJVkFURSBLRVktLS0tLQpNSUlFb3dJQkFBS0NBUUVBNnpiRkdXQVZpYlIy...QkVBRWFjY3BxaW9uNjFLaVdOcDU5T2YrUkdmCi0tLS0tRU5EIFJTQSBQUklWQVRFIEtFWS0tLS0tCg==

Package functions for interacting with Travis.