Public Documentation
Documentation for Documenter.jl
's public interface.
See Internal Documentation for internal package docs covering all submodules.
Contents
Index
Documenter
Documenter.Deps
DocumenterTools.Travis
Documenter.Deps.pip
Documenter.deploydocs
Documenter.hide
Documenter.makedocs
DocumenterTools.Travis.genkeys
DocumenterTools.generate
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.
Exports
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 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.
strict
– makedocs
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. Possible values are :html
(default), :latex
and :markdown
.
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. The keywords for the default HTML output are documented at the Writers.HTMLWriter
module.
Documenter also has (experimental) support for Markdown and LaTeX / PDF outputs. See the Other Output Formats for more information.
The Markdown and LaTeX output formats will be moved to a separate package in future versions of Documenter. Automatic documentation deployments should not rely on it unless they fix Documenter to a minor version.
See Also
A guide detailing how to document a package using Documenter's makedocs
is provided in the setup guide in the manual.
Documenter.hide
— Function.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", [...])
]
)
Documenter.deploydocs
— Function.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 linkvX.Y
pointing tovX.Y.Z
for highestX
,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.
Documenter.Deps
— Module.Exported module that provides build and deploy dependencies and related functions.
Currently only pip
is implemented.
Documenter.Deps.pip
— Function.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"),
# ...
)
DocumenterTools
DocumenterTools.generate
— Function.DocumenterTools.generate(path::String; name = nothing)
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.
Examples
julia> using DocumenterTools
julia> Documenter.generate("path/to/MyPackage/docs")
[ ... output ... ]
DocumenterTools.generate(pkg::Module; dir = "docs")
Same as generate(path::String)
but the path
and name is determined automatically from the module.
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 ... ]
DocumenterTools.Travis.genkeys
— Function.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
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==
DocumenterTools.Travis
— Module.Package functions for interacting with Travis.