CHANGELOG.md

Documenter.jl changelog

Version v0.22.0

• The assets and analytics arguments to makedocs have been deprecated in favor of the corresponding arguments of the Documenter.HTML format plugin. (#953)

  For upgrading: pass the corresponding arguments with the Documenter.HTML plugin instead. E.g. instead of

  makedocs(
      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 handle text/markdown output, which is preferred over text/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 to makedocs. (#980)

• Paths in include calls in @eval, @example, @repl and jldoctest blocks are now interpreted to be relative pwd, which is set to the output directory of the resulting file. (#941)

• deploydocs and git_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)

Version v0.21.5

• Deprecation warnings for format now get printed correctly when multiple formats are passed as a Vector. (#967)

Version v0.21.4

• A bug in jldoctest-blocks that, in rare cases, resulted in wrong output has been fixed. (#959, #960)

Version v0.21.3

• 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)

Version v0.21.2

• linkcheck now handles servers that do not support HEAD requests and properly checks for status codes of FTP responses. (#934)

Version v0.21.1

• @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)

Version v0.21.0

• The symbol values to the format argument of makedocs (:html, :markdown, :latex) have been deprecated in favor of the Documenter.HTML, Markdown and LaTeX objects. The Markdown and LaTeX 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 to makedocs 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 and html_edit_branch arguments to makedocs have been deprecated in favor of the corresponding arguments of the Documenter.HTML format plugin. (#864, #891)

  For upgrading: pass the corresponding arguments with the Documenter.HTML plugin instead. E.g. instead of

  makedocs(
      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 to makedocs as positional arguments to pass options to the extensions. (#864)

• @autodocs blocks now support the Filter 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 interpret DOCUMENTER_KEY. It now also uses the BatchMode SSH option and throws an error instead of asking for a passphrase and timing out the Travis build when DOCUMENTER_KEY is broken. (#697, #907)

• deploydocs now have a forcepush keyword argument that can be used to force-push the built documentation instead of adding a new commit. (#905)

Version v0.20.0

• 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/). The release-X.Y directories are no longer created. (#706, #813, #817)

    Technically, Documenter now deploys actual files only to dev/ and vX.Y.Z/ directories. The directories (URLs) that change from version to version (e.g. latest/, vX.Y) are implemented as symlinks on the gh-pages branch.

    The version selector will only display vX.Y/, stable/ and dev/ directories by default. This behavior can be customized with the versions keyword of deploydocs.

  • Documentation from the development branch (e.g. master) now deploys to dev/ by default (instead of latest/). This can be customized with the devurl keyword. (#802)

  • The latest keyword to deploydocs has been deprecated and renamed to devbranch. (#802)

  • The julia and osname keywords to deploydocs are now deprecated. (#816)

  • The default values of the target, deps and make keywords to deploydocs have been changed. See the default format change below for more information. (#826)

  For upgrading:

  • If you are using the latest keyword, then just use devbranch with the same value instead.

  • Update links that point to latest/ to point to dev/ instead (e.g. in the README).

  • Remove any links to the release-X.Y branches and remove the directories from your gh-pages branch.

  • The operating system and Julia version should be specified in the Travis build stage configuration (via julia: and os: options, see "Hosting Documentation" in the manual for more details) or by checking the TRAVIS_JULIA_VERSION and TRAVIS_OS_NAME environment variables in make.jl yourself.

• makedocs will now build Documenter's native HTML output by default and deploydocs' defaults now assume the HTML output. (#826)

  • The default value of the format keyword of makedocs has been changed to :html.

  • The default value of the target keyword to deploydocs has been changed to "build".

  • The default value of the make and deps keywords to deploydocs have been changed to nothing.

  For upgrading: If you are relying on the Markdown/MkDocs output, you now need to:

  • In makedocs, explicitly set format = :markdown

  • In deploydocs, explicitly set

    target = "site"
    deps = Deps.pip("pygments", "mkdocs")
    make = () -> run(`mkdocs build`)

  • Explicitly import DocumenterMarkdown in make.jl. See the MarkdownWriter 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 or using DocumenterLaTeX to make.jl.

• "Pretty URLs" are enabled by default now for the HTML output. The default value of the html_prettyurls has been changed to true.

  For a page foo/page.md Documenter now generates foo/page/index.html, instead of foo/page.html. On GitHub pages deployments it means that your URLs look like foo/page/ instead of foo/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 in makedocs. If you already set html_prettyurls, you do not need to change anything.

• The Travis.genkeys and Documenter.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 has show(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)