-
Documenter v0.23 requires Julia v1.0. (#1015)
-
DocTestSetup
s that are defined in@meta
blocks no longer apply to doctests that are in docstrings. (#774)-
Specifically, the pattern where
@docs
or@autodocs
blocks were surrounded by@meta
blocks, setting up a sharedDocTestSetup
for many docstrings, no longer works. -
Documenter now exports the
DocMeta
module, which provides an alternative way to addDocTestSetup
to docstrings.
For upgrading: Use
DocMeta.setdocmeta!
inmake.jl
to set up aDocTestSetup
that applies to all the docstrings in a particular module instead and, if applicable, remove the now redundant@meta
blocks. See the "Setup code" section under "Doctesting" in the manual for more information. -
-
makedocs
now accepts thedoctest = :only
keyword, which allows doctests to be run while most other build steps, such as rendering, are skipped. This makes it more feasible to run doctests as part of the test suite (see the manual for more information). (#198, #535, #756, #774) -
Documenter now exports the
doctest
function, which verifies the doctests in all the docstrings of a given module. This can be used to verify docstring doctests as part of test suite, or to fix doctests right in the REPL. (#198, #535, #756, #774, #1054) -
makedocs
now accepts theexpandfirst
argument, which allows specifying a set of pages that should be evaluated before others. (#1027, #1029) -
The evaluation order of pages is now fixed (unless customized with
expandfirst
). The pages are evaluated in the alphabetical order of their file paths. (#1027, #1029) -
The logo image in the HTML output will now always point to the first page in the navigation menu (as opposed to
index.html
, which may or may not exist). When using pretty URLs, theindex.html
part now omitted from the logo link URL. (#1005) -
Minor changes to how doctesting errors are printed. (#1028)
-
Videos can now be included in the HTML output using the image syntax (
![]()
) if the file extension matches a known format (.webm
,.mp4
,.ogg
,.ogm
,.ogv
,.avi
). (#1034) -
The HTML output now outputs HTML files for pages that are not referenced in the
pages
keyword too (Documenter finds them according to their extension). But they do exists outside of the standard navigation hierarchy (as defined bypages
). This fixes a bug where these pages could still be referenced by@ref
links and@contents
blocks, but in the HTML output, the links ended up being broken. (#1031, #1047) -
makedocs
now throws an error when the format objects (Documenter.HTML
,LaTeX
,Markdown
) get passed positionally. The format types are no longer subtypes ofDocumenter.Plugin
. (#1046, #1061) -
Doctesting now also handles doctests that contain invalid syntax and throw parsing errors. (#487, #1062)
-
Stacktraces in doctests that throw an error are now filtered more thoroughly, fixing an issue where too much of the stacktrace was included when
doctest
ormakedocs
was called from a more complicated context. (#1062) -
The current working directory when evaluating
@repl
and@example
blocks can now be set to a fixed directory by passing theworkdir
keyword tomakedocs
. The new keyword and its behaviour are experimental and not part of the public API. (#1013, #1025)
- Fix a test dependency problem revealed by a bugfix in Julia / Pkg. (#1037)
-
Documenter no longer crashes if the build includes doctests from docstrings that are defined in files that do not exist on the file system (e.g. if a Julia Base docstring is included when running a non-source Julia build). (#1002)
-
URLs for files in the repository are now generated correctly when the repository is used as a Git submodule in another repository. (#1000, #1004)
-
When checking for omitted docstrings, Documenter no longer gives "
Package.Package
missing" type false positives. (#1009) -
makedocs
again exits with an error ifstrict=true
and there is a doctest failure. (#1003, #1014)
- Fixed filepaths for images included in the .tex file for PDF output on Windows. (#999)
-
Error reporting for meta-blocks now handles missing files gracefully instead of throwing. (#996)
-
The
sitename
keyword argument todeploydocs
, which is required for the default HTML output, is now properly documented. (#995)
- Fixed a world-age related bug in doctests. (#994)
-
The
assets
andanalytics
arguments tomakedocs
have been deprecated in favor of the corresponding arguments of theDocumenter.HTML
format plugin. (#953)For upgrading: pass the corresponding arguments with the
Documenter.HTML
plugin instead. E.g. instead ofmakedocs( assets = ..., analytics = ..., ... )
you should have
makedocs( format = Documenter.HTML(assets = ..., analytics = ...), ... )
Note: It is technically possible to specify the same argument twice with different values by passing both variants. In that case the value passed to
makedocs
takes precedence. -
Documentation is no longer deployed on Travis CI cron jobs. (#917)
-
Log messages from failed
@meta
,@docs
,@autodocs
,@eval
,@example
and@setup
blocks now include information about the source location of the block. (#929) -
Docstrings from
@docs
-blocks are now included in the rendered docs even if some part(s) of the block failed. (#928, #935) -
The Markdown and LaTeX output writers can now handle multimedia output, such as images, from
@example
blocks. All the writers now also handletext/markdown
output, which is preferred overtext/plain
if available. (#938, #948) -
The HTML output now also supports SVG, WebP, GIF and JPEG logos. (#953)
-
Reporting of failed doctests are now using the logging system to be consistent with the rest of Documenter's output. (#958)
-
The construction of the search index in the HTML output has been refactored to make it easier to use with other search backends in the future. The structure of the generated search index has also been modified, which can yield slightly different search results. Documenter now depends on the lightweight JSON.jl package. (#966)
-
Docstrings that begin with an indented code block (such as a function signature) now have that block highlighted as Julia code by default. This behaviour can be disabled by passing
highlightsig=false
tomakedocs
. (#980) -
Paths in
include
calls in@eval
,@example
,@repl
andjldoctest
blocks are now interpreted to be relativepwd
, which is set to the output directory of the resulting file. (#941) -
deploydocs
andgit_push
now support non-github repos correctly and work when the.ssh
directory does not already exist or the working directory contains spaces. (#971) -
Tables now honor column alignment in the HTML output. If a column does not explicitly specify its alignment, the parser defaults to it being right-aligned, whereas previously all cells were left-aligned. (#511, #989)
-
Code lines ending with
# hide
are now properly hidden for CRLF inputs. (#991)
- Deprecation warnings for
format
now get printed correctly when multiple formats are passed as aVector
. (#967)
- A bug in
jldoctest
-blocks that, in rare cases, resulted in wrong output has been fixed. (#959, #960)
- The lunr.js and lodash JavaScript dependencies have been updated to their latest patch versions (from 2.3.1 to 2.3.5 and 4.17.4 to 4.17.11, respectively). This is in response to a vulnerability in lodash <4.17.11 (CVE-2018-16487). (#946)
-
linkcheck
now handles servers that do not supportHEAD
requests and properly checks for status codes of FTP responses. (#934)
-
@repl
blocks now work correctly together with quoted expressions. (#923, #926) -
@example
,@repl
and@eval
blocks now handle reserved words, e.g.try
/catch
, correctly. (#886, #927)
-
The symbol values to the
format
argument ofmakedocs
(:html
,:markdown
,:latex
) have been deprecated in favor of theDocumenter.HTML
,Markdown
andLaTeX
objects. TheMarkdown
andLaTeX
types are exported from the DocumenterMarkdown and DocumenterLaTeX packages, respectively. HTML output is still the default. (#891)For upgrading: If you don't specify
format
(i.e. you rely on the default) you don't have to do anything. Otherwise update calls tomakedocs
to use struct instances instead of symbols, e.g.makedocs( format = :markdown )
should be changed to
using DocumenterMarkdown makedocs( format = Markdown() )
-
The
html_prettyurls
,html_canonical
,html_disable_git
andhtml_edit_branch
arguments tomakedocs
have been deprecated in favor of the corresponding arguments of theDocumenter.HTML
format plugin. (#864, #891)For upgrading: pass the corresponding arguments with the
Documenter.HTML
plugin instead. E.g. instead ofmakedocs( html_prettyurls = ..., html_canonical = ..., ... )
you should have
makedocs( format = Documenter.HTML(prettyurls = ..., canonical = ...), ... )
Note: It is technically possible to specify the same argument twice with different values by passing both variants. In that case the value to the deprecated
html_*
variant takes precedence. -
Packages extending Documenter can now define subtypes of
Documenter.Plugin
, which can be passed tomakedocs
as positional arguments to pass options to the extensions. (#864) -
@autodocs
blocks now support theFilter
keyword, which allows passing a user-defined function that will filter the methods spliced in by the at-autodocs block. (#885) -
linkcheck
now supports checking URLs using the FTP protocol. (#879) -
Build output logging has been improved and switched to the logging macros from
Base
. (#876) -
The default
documenter.sty
LaTeX preamble now include\usepackage{graphicx}
. (#898) -
deploydocs
is now more helpful when it fails to interpretDOCUMENTER_KEY
. It now also uses theBatchMode
SSH option and throws an error instead of asking for a passphrase and timing out the Travis build whenDOCUMENTER_KEY
is broken. (#697, #907) -
deploydocs
now have aforcepush
keyword argument that can be used to force-push the built documentation instead of adding a new commit. (#905)
-
Documenter v0.20 requires at least Julia v0.7. (#795)
-
Documentation deployment via the
deploydocs
function has changed considerably.-
The user-facing directories (URLs) of different versions and what gets displayed in the version selector have changed. By default, Documenter now creates the
stable/
directory (as before) and a directory for every minor version (vX.Y/
). Therelease-X.Y
directories are no longer created. (#706, #813, #817)Technically, Documenter now deploys actual files only to
dev/
andvX.Y.Z/
directories. The directories (URLs) that change from version to version (e.g.latest/
,vX.Y
) are implemented as symlinks on thegh-pages
branch.The version selector will only display
vX.Y/
,stable/
anddev/
directories by default. This behavior can be customized with theversions
keyword ofdeploydocs
. -
Documentation from the development branch (e.g.
master
) now deploys todev/
by default (instead oflatest/
). This can be customized with thedevurl
keyword. (#802) -
The
latest
keyword todeploydocs
has been deprecated and renamed todevbranch
. (#802) -
The
julia
andosname
keywords todeploydocs
are now deprecated. (#816) -
The default values of the
target
,deps
andmake
keywords todeploydocs
have been changed. See the default format change below for more information. (#826)
For upgrading:
-
If you are using the
latest
keyword, then just usedevbranch
with the same value instead. -
Update links that point to
latest/
to point todev/
instead (e.g. in the README). -
Remove any links to the
release-X.Y
branches and remove the directories from yourgh-pages
branch. -
The operating system and Julia version should be specified in the Travis build stage configuration (via
julia:
andos:
options, see "Hosting Documentation" in the manual for more details) or by checking theTRAVIS_JULIA_VERSION
andTRAVIS_OS_NAME
environment variables inmake.jl
yourself.
-
-
makedocs
will now build Documenter's native HTML output by default anddeploydocs
' defaults now assume the HTML output. (#826)-
The default value of the
format
keyword ofmakedocs
has been changed to:html
. -
The default value of the
target
keyword todeploydocs
has been changed to"build"
. -
The default value of the
make
anddeps
keywords todeploydocs
have been changed tonothing
.
For upgrading: If you are relying on the Markdown/MkDocs output, you now need to:
-
In
makedocs
, explicitly setformat = :markdown
-
In
deploydocs
, explicitly settarget = "site" deps = Deps.pip("pygments", "mkdocs") make = () -> run(`mkdocs build`)
-
Explicitly import
DocumenterMarkdown
inmake.jl
. See theMarkdownWriter
deprecation below.
If you already specify any of the changed keywords, then you do not need to make any changes to those keywords you already set.
However, if you are setting any of the values to the new defaults (e.g. when you are already using the HTML output), you may now rely on the new defaults.
-
-
The Markdown/MkDocs (
format = :markdown
) and PDF/LaTeX (format = :latex
) outputs now require an external package to be loaded (DocumenterMarkdown and DocumenterLaTeX, respectively). (#833)For upgrading: Make sure that the respective extra package is installed and then just add
using DocumenterMarkdown
orusing DocumenterLaTeX
tomake.jl
. -
"Pretty URLs" are enabled by default now for the HTML output. The default value of the
html_prettyurls
has been changed totrue
.For a page
foo/page.md
Documenter now generatesfoo/page/index.html
, instead offoo/page.html
. On GitHub pages deployments it means that your URLs look likefoo/page/
instead offoo/page.html
.For local builds you should explicitly set
html_prettyurls = false
.For upgrading: If you wish to retain the old behavior, set
html_prettyurls = false
inmakedocs
. If you already sethtml_prettyurls
, you do not need to change anything. -
The
Travis.genkeys
andDocumenter.generate
functions have been moved to a separate DocumenterTools.jl package. (#789) -
If Documenter is not able to determine which Git hosting service is being used to host the source, the "Edit on XXX" links become "Edit source" with a generic icon. (#804)
-
The at-blocks now support
MIME"text/html"
rendering of objects (e.g. for interactive plots). I.e. if a type hasshow(io, ::MIME"text/html", x)
defined, Documenter now uses that when rendering the objects in the document. (#764) -
Enhancements to the sidebar. When loading a page, the sidebar will jump to the current page now. Also, the scrollbar in WebKit-based browsers look less intrusive now. (#792, #854, #863)
-
Minor style enhancements to admonitions. (#841)
-
The at-blocks that execute code can now handle
include
statements. (#793, #794) -
At-docs blocks no longer give an error when containing empty lines. (#823, #824)