Skip to content

Commit

Permalink
Change format::Symbol to format::Plugin.
Browse files Browse the repository at this point in the history
  • Loading branch information
fredrikekre committed Dec 9, 2018
1 parent 773f258 commit 395df27
Show file tree
Hide file tree
Showing 19 changed files with 407 additions and 230 deletions.
1 change: 1 addition & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -8,5 +8,6 @@ test/missingdocs/build/
test/nongit/build/
test/errors/build/
docs/build/
docs/pdf/build/
docs/site/
docs/Manifest.toml
10 changes: 9 additions & 1 deletion .travis.yml
Original file line number Diff line number Diff line change
Expand Up @@ -18,10 +18,18 @@ after_success:

jobs:
include:
- stage: "Documentation"
- stage: "Documentation/HTML"
julia: 1.0
os: linux
script:
- julia --project=docs/ -e 'using Pkg; Pkg.develop(PackageSpec(path=pwd())); Pkg.instantiate()'
- julia --project=docs/ docs/make.jl
after_success: skip
- stage: "Documentation/PDF"
julia: 1.0
os: linux
services: docker
script:
- julia --project=docs/pdf/ -e 'using Pkg; Pkg.instantiate()'
- julia --project=docs/pdf/ docs/pdf/make.jl
after_success: skip
33 changes: 28 additions & 5 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,28 +2,50 @@

## Version `v0.21.0`

* ![Enhancement][badge-enhancement] ![Deprecation][badge-deprecation] The options to `HTMLWriter` should now be passed using the `Documenter.HTML` plugin. ([#864][github-864])
* ![Deprecation][badge-deprecation] The `format` argument to `makedocs`
have changed from `:html`/`:markdown`/`:latex` to instances of the `Documenter.HTML`/`Markdown`/`LaTeX`
structs, where `Markdown` and `LaTeX` are exported from `DocumenterMarkdown` and `DocumenterLaTeX`
respectively. HTML output is still the default. ([#891][github-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()
)
```

* ![Enhancement][badge-enhancement] ![Deprecation][badge-deprecation] The options to `HTMLWriter` should now be
passed to the `Documenter.HTML` format specifier instead. ([#864][github-864], [#891][github-891])

- `html_prettyurls`, `html_canonical`, `html_disable_git` and `html_edit_branch` arguments to `makedocs` have been deprecated.

**For upgrading:** pass the corresponding arguments with the `Documenter.HTML` plugin instead. E.g. instead of
```
makedocs(
html_prettyurls = ...,
html_prettyurls = ..., html_canonical = ...,
...
)
```
you should have
```
makedocs(
Documenter.HTML(prettyurls = ...),
format = Documenter.HTML(prettyurls = ..., canonical = ...),
...
)
```

- 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.
* ![Feature][badge-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][github-864])

* ![Feature][badge-feature] at-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][github-885])
* ![Feature][badge-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][github-885])

* ![Enhancement][badge-enhancement] `linkcheck` now supports checking URLs using the FTP protocol. ([#879][github-879])

Expand Down Expand Up @@ -137,6 +159,7 @@
[github-876]: https://github.com/JuliaDocs/Documenter.jl/pull/876
[github-879]: https://github.com/JuliaDocs/Documenter.jl/pull/879
[github-885]: https://github.com/JuliaDocs/Documenter.jl/pull/885
[github-891]: https://github.com/JuliaDocs/Documenter.jl/pull/891
[github-898]: https://github.com/JuliaDocs/Documenter.jl/pull/898


Expand Down
11 changes: 5 additions & 6 deletions docs/make.jl
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,11 @@ using Documenter, DocumenterTools

makedocs(
modules = [Documenter, DocumenterTools],
format = Documenter.HTML(
# Use clean URLs, unless built as a "local" build
prettyurls = !("local" in ARGS),
canonical = "https://juliadocs.github.io/Documenter.jl/stable/",
),
clean = false,
assets = ["assets/favicon.ico"],
sitename = "Documenter.jl",
Expand Down Expand Up @@ -35,7 +40,6 @@ makedocs(
"lib/internals/documents.md",
"lib/internals/dom.md",
"lib/internals/expanders.md",
"lib/internals/formats.md",
"lib/internals/mdflatten.md",
"lib/internals/selectors.md",
"lib/internals/textdiff.md",
Expand All @@ -45,11 +49,6 @@ makedocs(
],
"contributing.md",
],
Documenter.HTML(
# Use clean URLs, unless built as a "local" build
prettyurls = !("local" in ARGS),
canonical = "https://juliadocs.github.io/Documenter.jl/stable/",
),
)

deploydocs(
Expand Down
93 changes: 93 additions & 0 deletions docs/pdf/Manifest.toml
Original file line number Diff line number Diff line change
@@ -0,0 +1,93 @@
[[Base64]]
uuid = "2a0f44e3-6c83-55bd-87e4-b1978d98bd5f"

[[Dates]]
deps = ["Printf"]
uuid = "ade2ca70-3891-5945-98fb-dc099432e06a"

[[Distributed]]
deps = ["LinearAlgebra", "Random", "Serialization", "Sockets"]
uuid = "8ba89e20-285c-5b6f-9357-94700520ee1b"

[[DocStringExtensions]]
deps = ["LibGit2", "Markdown", "Pkg", "Test"]
git-tree-sha1 = "1df01539a1c952cef21f2d2d1c092c2bcf0177d7"
uuid = "ffbed154-4ef7-542d-bbb7-c09d3a79fcae"
version = "0.6.0"

[[Documenter]]
deps = ["Base64", "DocStringExtensions", "InteractiveUtils", "LibGit2", "Logging", "Markdown", "Pkg", "REPL", "Random", "Test", "Unicode"]
path = "../.."
uuid = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
version = "0.20.0+"

[[DocumenterLaTeX]]
deps = ["Documenter"]
git-tree-sha1 = "653299370be20ff580bccd707dc9f360c0852d7f"
repo-rev = "fe/ltx"
repo-url = "https://github.com/JuliaDocs/DocumenterLaTeX.jl.git"
uuid = "cd674d7a-5f81-5cf3-af33-235ef1834b99"
version = "0.1.0"

[[DocumenterTools]]
deps = ["Base64", "DocStringExtensions", "LibGit2", "Pkg", "Test"]
git-tree-sha1 = "f5803a9c2c23ff226e8eab2df7ac4c75e77a0d53"
uuid = "35a29f4d-8980-5a13-9543-d66fff28ecb8"
version = "0.1.0"

[[InteractiveUtils]]
deps = ["LinearAlgebra", "Markdown"]
uuid = "b77e0a4c-d291-57a0-90e8-8db25a27a240"

[[LibGit2]]
uuid = "76f85450-5226-5b5a-8eaa-529ad045b433"

[[Libdl]]
uuid = "8f399da3-3557-5675-b5ff-fb832c97cbdb"

[[LinearAlgebra]]
deps = ["Libdl"]
uuid = "37e2e46d-f89d-539d-b4ee-838fcccc9c8e"

[[Logging]]
uuid = "56ddb016-857b-54e1-b83d-db4d58db5568"

[[Markdown]]
deps = ["Base64"]
uuid = "d6f4376e-aef5-505a-96c1-9c027394607a"

[[Pkg]]
deps = ["Dates", "LibGit2", "Markdown", "Printf", "REPL", "Random", "SHA", "UUIDs"]
uuid = "44cfe95a-1eb2-52ea-b672-e2afdf69b78f"

[[Printf]]
deps = ["Unicode"]
uuid = "de0858da-6303-5e67-8744-51eddeeeb8d7"

[[REPL]]
deps = ["InteractiveUtils", "Markdown", "Sockets"]
uuid = "3fa0cd96-eef1-5676-8a61-b3b8758bbffb"

[[Random]]
deps = ["Serialization"]
uuid = "9a3f8284-a2c9-5f02-9a11-845980a1fd5c"

[[SHA]]
uuid = "ea8e919c-243c-51af-8825-aaa63cd721ce"

[[Serialization]]
uuid = "9e88b42a-f829-5b0c-bbe9-9e923198166b"

[[Sockets]]
uuid = "6462fe0b-24de-5631-8697-dd941f90decc"

[[Test]]
deps = ["Distributed", "InteractiveUtils", "Logging", "Random"]
uuid = "8dfed614-e22c-5e08-85e1-65c5234f0b40"

[[UUIDs]]
deps = ["Random"]
uuid = "cf7118a7-6976-5b1a-9a39-7adc72f591a4"

[[Unicode]]
uuid = "4ec0a83e-493e-50e2-b9ac-8f72acf5a8f5"
5 changes: 5 additions & 0 deletions docs/pdf/Project.toml
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
[deps]
Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
DocumenterLaTeX = "cd674d7a-5f81-5cf3-af33-235ef1834b99"
DocumenterTools = "35a29f4d-8980-5a13-9543-d66fff28ecb8"
Test = "8dfed614-e22c-5e08-85e1-65c5234f0b40"
65 changes: 65 additions & 0 deletions docs/pdf/make.jl
Original file line number Diff line number Diff line change
@@ -0,0 +1,65 @@
using Documenter, DocumenterTools, DocumenterLaTeX
using Test

const ROOT = joinpath(@__DIR__, "..")

# Documenter package docs
doc = makedocs(
debug = true,
root = ROOT,
build = "pdf/build",
modules = [Documenter, DocumenterTools],
clean = false,
format = LaTeX(platform = "docker"),
sitename = "Documenter.jl",
authors = "Michael Hatherly, Morten Piibeleht, and contributors.",
pages = [
"Home" => "index.md",
"Manual" => Any[
"Guide" => "man/guide.md",
"man/examples.md",
"man/syntax.md",
"man/doctests.md",
"man/latex.md",
hide("man/hosting.md", [
"man/hosting/walkthrough.md"
]),
"man/other-formats.md",
],
"Library" => Any[
"Public" => "lib/public.md",
hide("Internals" => "lib/internals.md", Any[
"lib/internals/anchors.md",
"lib/internals/builder.md",
"lib/internals/cross-references.md",
"lib/internals/docchecks.md",
"lib/internals/docsystem.md",
"lib/internals/doctests.md",
"lib/internals/documenter.md",
"lib/internals/documentertools.md",
"lib/internals/documents.md",
"lib/internals/dom.md",
"lib/internals/expanders.md",
"lib/internals/mdflatten.md",
"lib/internals/selectors.md",
"lib/internals/textdiff.md",
"lib/internals/utilities.md",
"lib/internals/writers.md",
])
],
"contributing.md",
]
);

# hack to only deploy the actual pdf-file
mkpath(joinpath(ROOT, "pdf", "build", "pdfdir"))
mv(joinpath(ROOT, "pdf", "build", "Documenter.jl.pdf"),
joinpath(ROOT, "pdf", "build", "pdfdir", "Documenter.jl.pdf"))


deploydocs(
repo = "github.com/JuliaDocs/Documenter.jl.git",
root = ROOT,
target = "pdf/build/pdfdir",
branch = "gh-pages-pdf",
)
5 changes: 0 additions & 5 deletions docs/src/lib/internals/formats.md

This file was deleted.

36 changes: 32 additions & 4 deletions docs/src/man/other-formats.md
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,7 @@ You also need to import the package in `make.jl`:
using DocumenterMarkdown
```

When `DocumenterMarkdown` is loaded, you can specify `format = :markdown` in [`makedocs`](@ref).
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.

Expand Down Expand Up @@ -156,14 +156,42 @@ package to be available and loaded in `make.jl` with
using DocumenterLaTeX
```

When `DocumenterLaTeX` is loaded, you can set `format = :latex` in [`makedocs`](@ref),
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 should also specify the `sitename` and `authors` keywords for `makedocs` when using the
LaTeX output.

### Compiling using natively installed latex

The following is required to build the documentation:

* 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
highlighter [Pygments](http://pygments.org/) installed.
* You need the [Lato](http://www.latofonts.com/lato-free-fonts/) and
[Roboto Mono](https://fonts.google.com/specimen/Roboto+Mono) fonts installed.

You should also specify the `sitename` and `authors` keywords for `makedocs` when using the
LaTeX output.
### Compiling using docker image

It is also possible to use a prebuilt [docker image](https://hub.docker.com/r/juliadocs/documenter-latex/)
to compile the `.tex` file. The image contains all of the required installs described in the section
above. The only requirement for using the image is that `docker` is installed and available for
the builder to call. You also need to tell Documenter to use the docker image, instead of natively
installed tex which is the default. This is done with the `LaTeX` specifier:

```
using DocumenterLaTeX
makedocs(
format = LaTeX(platform = "docker"),
...
)
```

If you build the documentation on Travis you need to add

```
services:
- docker
```

to your `.travis.yml` file.
Loading

0 comments on commit 395df27

Please sign in to comment.