From 5596d1db697c2bde2354d9e82d9292cc52e2e3b5 Mon Sep 17 00:00:00 2001 From: Morten Piibeleht Date: Thu, 20 Sep 2018 22:37:55 +1200 Subject: [PATCH] Deprecate Markdown/LaTeX writers as built-ins (#833) In favor of DocumenterMarkdown and DocumenterLaTeX packages. --- docs/src/man/other-formats.md | 46 ++++++++++++++++------------- src/Writers/Writers.jl | 55 +++++++++++++++++++++++++++++++++++ 2 files changed, 81 insertions(+), 20 deletions(-) diff --git a/docs/src/man/other-formats.md b/docs/src/man/other-formats.md index 95b5c9b0c0..639c3313b0 100644 --- a/docs/src/man/other-formats.md +++ b/docs/src/man/other-formats.md @@ -1,13 +1,24 @@ # Other outputs -In addition to the default native HTML output, Documenter can also generate output in other -formats. The output format can be specified using the `format` option in [`makedocs`](@ref). +In addition to the default native HTML output, plugin packages enable Documenter to generate +output in other formats. Once the corresponding package is loadded, the output format can be +specified using the `format` option in [`makedocs`](@ref). + ## Markdown & MkDocs -By specifying `format = :markdown` in [`makedocs`](@ref), Documenter will output a set of -Markdown files to the `build` directory that can then further be processed with -[MkDocs](https://www.mkdocs.org/) into HTML pages. +Markdown output requires the [`DocumenterMarkdown`](https://github.com/JuliaDocs/DocumenterMarkdown.jl) +package to be available and loaded. +For Travis setups, add the package to the `docs/Project.toml` environment as a dependency. +You also need to import the package in `make.jl`: + +``` +using DocumenterMarkdown +``` + +When `DocumenterMarkdown` is loaded, you can specify `format = :markdown` in [`makedocs`](@ref). +Documenter will then output a set of Markdown files to the `build` directory that can then +further be processed with [MkDocs](https://www.mkdocs.org/) into HTML pages. MkDocs, of course, is not the only option you have -- any markdown to HTML converter should work fine with some amount of setting up. @@ -17,12 +28,6 @@ work fine with some amount of setting up. Markdown output used to be the default option (i.e. when leaving the `format` option unspecified). The default now is the HTML output. -!!! warning - - Markdown output 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. - ### The MkDocs `mkdocs.yml` File A MkDocs build is controlled by the `mkdocs.yml` configuration file. Add the file with the @@ -142,10 +147,17 @@ enable properly rendered mathematical equations within your documentation both l when built and deployed using the Travis built service. -## LaTeX +## PDF output via LaTeX -By setting `format = :latex`, you can use LaTeX to generate a PDF version of your -documentation. +LaTeX/PDF output requires the [`DocumenterLaTeX`](https://github.com/JuliaDocs/DocumenterLaTeX.jl) +package to be available and loaded in `make.jl` with + +``` +using DocumenterLaTeX +``` + +When `DocumenterLaTeX` is loaded, you can set `format = :latex` in [`makedocs`](@ref), +and Documenter will generate a PDF version of the documentation using LaTeX. * You need `pdflatex` command to be installed and available to Documenter. * You need the [minted](https://ctan.org/pkg/minted) LaTeX package and its backend source @@ -155,9 +167,3 @@ documentation. You should also specify the `sitename` and `authors` keywords for `makedocs` when using the LaTeX output. - -!!! warning - - The LaTeX output 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. diff --git a/src/Writers/Writers.jl b/src/Writers/Writers.jl index 2613ce464a..37b518c7f3 100644 --- a/src/Writers/Writers.jl +++ b/src/Writers/Writers.jl @@ -62,6 +62,37 @@ function render(doc::Documents.Document) # Render each format. Additional formats must define an `order`, `matcher`, `runner`, as # well as their own rendering methods in a separate module. for each in doc.user.format + if each === :markdown && !backends_enabled[:markdown] + @warn """Deprecated format value :markdown + + The Markdown/MkDocs backend must now be imported from a separate package. + Add DocumenterMarkdown to your documentation dependencies and add + + using DocumenterMarkdown + + to your make.jl script. + + Built-in support for format=:markdown will be removed completely in a future + Documenter version, causing builds to fail completely. + + See the Output Backends section in the manual for more information. + """ + elseif each === :latex && !backends_enabled[:latex] + @warn """Deprecated format value :markdown + + The LaTeX/PDF backend must now be imported from a separate package. + Add DocumenterLaTeX to your documentation dependencies and add + + using DocumenterLaTeX + + to your make.jl script. + + Built-in support for format=:latex will be removed completely in a future + Documenter version, causing builds to fail completely. + + See the Output Backends section in the manual for more information. + """ + end Selectors.dispatch(FormatSelector, each, doc) end # Revert all local links to their original URLs. @@ -74,4 +105,28 @@ include("MarkdownWriter.jl") include("HTMLWriter.jl") include("LaTeXWriter.jl") +# This is hack to enable shell packages that would behave as in the supplementary Writer +# modules have been moved out of Documenter. +# +# External packages DocumenterMarkdown and DocumenterLaTeX can use the enable_backend +# function to mark that a certain backend is loaded in backends_enabled. That is used to +# determine whether a deprecation warning should be printed in the render method above. +# +# enable_backend() is not part of the API and will be removed as soon as LaTeXWriter and +# MarkdownWriter are actually moved out into a separate module (TODO). +backends_enabled = Dict( + :markdown => false, + :latex => false +) + +function enable_backend(backend::Symbol) + global backends_enabled + if backend in keys(backends_enabled) + backends_enabled[backend] = true + else + @error "Unknown backend. Expected one of:" keys(backends_enabled) + throw(ArgumentError("Unknown backend $backend.")) + end +end + end