Public Documentation

Documentation for Documenter.jl's public interface.

See Internal Documentation for internal package docs covering all submodules.

Contents

Index

Public Interface

#Documenter — Module.

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.

Exports

source

#Documenter.makedocs — Function.

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

See Also

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

source

#Documenter.deploydocs — Function.

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. 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. By default this value is set 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 dependancies 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.

source

#Documenter.generate — Function.

Signatures

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

source

#Documenter.Travis — Module.

Package functions for interacting with Travis.

Exports

source

#Documenter.Travis.genkeys — Function.

Signatures

genkeys(package)

Generate ssh keys for package package to automatically deploy docs from Travis to GitHub pages. Requires the following command lines programs to be installed:

  • which
  • git
  • travis
  • ssh-keygen

Examples

julia> using Documenter

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

source

#Documenter.Deps — Module.

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

Currently only pip is implemented.

source

#Documenter.Deps.pip — Function.

Signatures

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