Skip to content

Latest commit

 

History

History
609 lines (413 loc) · 40.7 KB

CHANGELOG.md

File metadata and controls

609 lines (413 loc) · 40.7 KB
Raw

Documenter.jl changelog

Version v0.25.0

  • Enhancement When deploying with deploydocs, any SSH username can now be used (not just git), by prepending username@ to the repository URL in the repo argument. (#1285)

  • Enhancement The first link fragment on each page now omits the number; before the rendering resulted in: #foobar-1, #foobar-2, and now: #foobar, #foobar-2. For backwards compatibility the old fragments are also inserted such that old links will still point to the same location. (#1292)

  • Enhancement When deploying on CI with deploydocs, the build information in the version number (i.e. what comes after +) is now discarded when determining the destination directory. This allows custom tags to be used to fix documentation build and deployment issues for versions that have already been registered. (#1298)

  • Enhancement You can now optionally choose to push pull request preview builds to a different branch and/or different repository than the main docs builds, by setting the optional branch_previews and/or repo_previews keyword arguments to the deploydocs function. Also, you can now optionally choose to use a different SSH key for preview builds, by setting the optional DOCUMENTER_KEY_PREVIEWS environment variable; if the DOCUMENTER_KEY_PREVIEWS environment variable is not set, then the regular DOCUMENTER_KEY environment variable will be used. (#1307, #1310, #1315)

  • Bugfix Deps.pip is again a closure and gets executed during the deploydocs call, not before it. (#1240)

  • Bugfix Custom assets (CSS, JS etc.) for the HTML build are now again included as the very last elements in the <head> tag so that it would be possible to override default the default assets. (#1328)

  • Bugfix Docstrings from @autodocs blocks are no longer sorted according to an undocumented rule where exported names should come before unexported names. Should this behavior be necessary, the @autodocs can be replaced by two separate blocks that use the Public and Private options to filter out the unexported or exported docstrings in the first or the second block, respectively. (#964, #1323)

Version v0.24.11

  • Bugfix Some sections and page titles that were missing from the search results in the HTML backend now show up. (#1311)

Version v0.24.10

  • Enhancement The curl timeout when checking remote links is now configurable with the linkcheck_timeout keyword. (#1057, #1295)

  • Bugfix Special characters are now properly escaped in admonition titles in LaTeX/PDF builds and do not cause the PDF build to fail anymore. (#1299)

Version v0.24.9

  • Bugfix Canonical URLs are now properly prettified (e.g. /path/ instead of /path/index.html) when using prettyurls=true. (#1293)

Version v0.24.8

  • Enhancement Non-standard admonition categories are (again) applied to the admonition <div> elements in HTML output (as is-category-$category). (#1279, #1280)

Version v0.24.7

  • Bugfix Remove only, a new export from Base on Julia 1.4, from the JS search filter. (#1264)

  • Bugfix Fix errors in LaTeX builds due to bad escaping of certain characters. (#1118, #1119, #1200, #1269)

Version v0.24.6

  • Enhancement Reorganize some of the internal variables in Documenter's Sass sources, to make it easier to create custom themes on top of the Documenter base theme. (#1258)

Version v0.24.5

  • Enhancement Bugfix Documenter now correctly emulates the "REPL softscope" (Julia 1.5) in REPL-style doctest blocks and @repl blocks. (#1232)

Version v0.24.4

  • Enhancement Change the inline code to less distracting black color in the HTML light theme. (#1212, #1222)

  • Enhancement Add the ability specify the lang attribute of the html tag in the HTML output, to better support documentation pages in other languages. By default Documenter now defaults to lang="en". (#1223)

Version v0.24.3

  • Bugfix Fix a case where Documenter's deployment would fail due to git picking up the wrong ssh config file on non-standard systems. (#1216)

Version v0.24.2

  • Maintenance Improvements to logging in deploydocs. (#1195)

Version v0.24.1

  • Bugfix Fix a bad mktempdir incantation in LaTeXWriter. (#1194)

Version v0.24.0

  • BREAKING Documenter no longer creates a symlink between the old latest url to specified devurl. (#1151)

    For upgrading: Make sure that links to the latest documentation have been updated (e.g. the package README).

  • BREAKING The deprecated makedocs keywords (html_prettyurls, html_disable_git, html_edit_branch, html_canonical, assets, analytics) have been removed. (#1107)

    For upgrading: Pass the corresponding values to the HTML constructor when settings the format keyword.

  • Feature Documenter can now deploy preview documentation from pull requests (with head branch in the same repository, i.e. not from forks). This is enabled by passing push_preview=true to deploydocs. (#1180)

  • Enhancement The Documenter HTML front end now uses KaTeX as the default math rendering engine. (#1097)

    Possible breakage: This may break the rendering of equations that use some more esoteric features that are only supported in MathJax. It is possible to switch back to MathJax by passing mathengine = Documenter.MathJax() to the HTML constructor in the format keyword.

  • Enhancement The HTML front end generated by Documenter has been redesigned and now uses the Bulma CSS framework. (#1043)

    Possible breakage: Packages overriding the default Documenter CSS file, relying on some external CSS or relying on Documenter's CSS working in a particular way will not build correct-looking sites. Custom themes should now be developed as Sass files and compiled together with the Documenter and Bulma Sass dependencies (under assets/html/scss).

  • Deprecation Enhancement The edit_branch keyword to Documenter.HTML has been deprecated in favor of the new edit_link keyword. As a new feature, passing edit_link = nothing disables the "Edit on GitHub" links altogether. (#1173)

    For upgrading: If using edit_branch = nothing, use edit_link = :commit instead. If passing a String to edit_branch, pass that to edit_link instead.

  • Feature Deployment is now more customizable and thus not as tied to Travis CI as before. (#1147, #1171, #1180)

  • Feature Documenter now has builtin support for deploying from GitHub Actions. Documenter will autodetect the running system, unless explicitly specified. (#1144, #1152)

  • Feature When using GitHub Actions Documenter will (try to) post a GitHub status with a link to the generated documentation. This is especially useful for pull request preview builds (see above). (#1186)

  • Enhancement The handling of JS and CSS assets is now more customizable:

    • The asset function can now be used to declare remote JS and CSS assets in the assets keyword. (#1108)
    • The highlights keyword to HTML can be used to declare additional languages that should be highlighted in code blocks. (#1094)
    • It is now possible to choose between MathJax and KaTeX as the math rendering engine with the mathengine keyword to HTML and to set their configuration in the make.jl script directly. (#1097)

  • Enhancement The JS and CSS dependencies of the front end have been updated to the latest versions. (#1189)

  • Enhancement Displaying of the site name at the top of the sidebar can now be disabled by passing sidebar_sitename = false to HTML in the format keyword. (#1089)

  • Enhancement For deployments that have Google Analytics enabled, the URL fragment (i.e. the in-page # target) also stored in analytics. (#1121)

  • Enhancement Page titles are now boosted in the search, yielding better search results. (#631, #1112, #1113)

  • Enhancement In the PDF/LaTeX output, images that are wider than the text are now being scaled down to text width automatically. The PDF builds now require the adjustbox LaTeX package to be available. (#1137)

  • Enhancement If the TeX compilation fails for the PDF/LaTeX output, makedocs now throws an exception. (#1166)

  • Bugfix LaTeXWriter now outputs valid LaTeX if an @contents block is nested by more than two levels, or if @contents or @index blocks do not contain any items. (#1166)

Version v0.23.4

  • Bugfix The include and eval functions are also available in @setup blocks now. (#1148, #1153)

Version v0.23.3

  • Bugfix Fix file permission error when Pkg.testing Documenter. (#1115)

Version v0.23.2

  • Bugfix Empty Markdown headings no longer cause Documenter to crash. (#1081, #1082)

Version v0.23.1

  • Bugfix Documenter no longer throws an error if the provided EditURL argument is missing. (#1076, #1077)

  • Bugfix Non-standard Markdown AST nodes no longer cause Documenter to exit with a missing method error in doctesting and HTML output. Documenter falls back to repr() for such nodes. (#1073, #1075)

  • Bugfix Docstrings parsed into nested Markdown.MD objects are now unwrapped correctly and do not cause Documenter to crash with a missing method error anymore. The user can run into that when reusing docstrings with the @doc @doc(foo) function bar end pattern. (#1075)

Version v0.23.0

  • Documenter v0.23 requires Julia v1.0. (#1015)

  • BREAKING DocTestSetups 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 shared DocTestSetup for many docstrings, no longer works.

    • Documenter now exports the DocMeta module, which provides an alternative way to add DocTestSetup to docstrings.

    For upgrading: Use DocMeta.setdocmeta! in make.jl to set up a DocTestSetup 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.

  • Feature makedocs now accepts the doctest = :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)

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

  • Feature makedocs now accepts the expandfirst argument, which allows specifying a set of pages that should be evaluated before others. (#1027, #1029)

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

  • Enhancement 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, the index.html part now omitted from the logo link URL. (#1005)

  • Enhancement Minor changes to how doctesting errors are printed. (#1028)

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

  • Enhancement The PDF output now uses the DejaVu Sans and DejaVu Sans Mono fonts to provide better Unicode coverage. (#803, #1066)

  • Bugfix 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 by pages). 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)

  • Bugfix makedocs now throws an error when the format objects (Documenter.HTML, LaTeX, Markdown) get passed positionally. The format types are no longer subtypes of Documenter.Plugin. (#1046, #1061)

  • Bugfix Doctesting now also handles doctests that contain invalid syntax and throw parsing errors. (#487, #1062)

  • Bugfix 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 or makedocs was called from a more complicated context. (#1062)

  • Experimental Feature The current working directory when evaluating @repl and @example blocks can now be set to a fixed directory by passing the workdir keyword to makedocs. The new keyword and its behaviour are experimental and not part of the public API. (#1013, #1025)

Version v0.22.6

  • Maintenance Add DocStringExtensions 0.8 as an allowed dependency version. (#1071)

Version v0.22.5

  • Maintenance Fix a test dependency problem revealed by a bugfix in Julia / Pkg. (#1037)

Version v0.22.4

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

  • Bugfix URLs for files in the repository are now generated correctly when the repository is used as a Git submodule in another repository. (#1000, #1004)

  • Bugfix When checking for omitted docstrings, Documenter no longer gives "Package.Package missing" type false positives. (#1009)

  • Bugfix makedocs again exits with an error if strict=true and there is a doctest failure. (#1003, #1014)

Version v0.22.3

  • Bugfix Fixed filepaths for images included in the .tex file for PDF output on Windows. (#999)

Version v0.22.2

  • Bugfix Error reporting for meta-blocks now handles missing files gracefully instead of throwing. (#996)

  • Enhancement The sitename keyword argument to deploydocs, which is required for the default HTML output, is now properly documented. (#995)

Version v0.22.1

  • Bugfix Fixed a world-age related bug in doctests. (#994)

Version v0.22.0

  • Deprecation Enhancement 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.

  • Enhancement Documentation is no longer deployed on Travis CI cron jobs. (#917)

  • Enhancement Log messages from failed @meta, @docs, @autodocs, @eval, @example and @setup blocks now include information about the source location of the block. (#929)

  • Enhancement Docstrings from @docs-blocks are now included in the rendered docs even if some part(s) of the block failed. (#928, #935)

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

  • Enhancement The HTML output now also supports SVG, WebP, GIF and JPEG logos. (#953)

  • Enhancement Reporting of failed doctests are now using the logging system to be consistent with the rest of Documenter's output. (#958)

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

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

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

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

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

  • Bugfix Code lines ending with # hide are now properly hidden for CRLF inputs. (#991)

Version v0.21.5

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

Version v0.21.4

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

Version v0.21.3

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

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

Version v0.21.1

  • Bugfix @repl blocks now work correctly together with quoted expressions. (#923, #926)

  • Bugfix @example, @repl and @eval blocks now handle reserved words, e.g. try/catch, correctly. (#886, #927)

Version v0.21.0

  • Deprecation Enhancement 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()
)

  • Deprecation Enhancement 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.

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

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

  • Enhancement linkcheck now supports checking URLs using the FTP protocol. (#879)

  • Enhancement Build output logging has been improved and switched to the logging macros from Base. (#876)

  • Enhancement The default documenter.sty LaTeX preamble now include \usepackage{graphicx}. (#898)

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

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

  • BREAKING 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.

  • BREAKING 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.

  • Deprecation 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.

  • BREAKING "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.

  • BREAKING The Travis.genkeys and Documenter.generate functions have been moved to a separate DocumenterTools.jl package. (#789)

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

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

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

  • Enhancement Minor style enhancements to admonitions. (#841)

  • Bugfix The at-blocks that execute code can now handle include statements. (#793, #794)

  • Bugfix At-docs blocks no longer give an error when containing empty lines. (#823, #824)