Change format::Symbol to format::Plugin.

JuliaDocs · Dec 9, 2018 · 395df27 · 395df27
1 parent 773f258
commit 395df27
Show file tree

Hide file tree

Showing 19 changed files with 407 additions and 230 deletions.
diff --git a/.gitignore b/.gitignore
@@ -8,5 +8,6 @@ test/missingdocs/build/
 test/nongit/build/
 test/errors/build/
 docs/build/
+docs/pdf/build/
 docs/site/
 docs/Manifest.toml
diff --git a/.travis.yml b/.travis.yml
@@ -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
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -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])
 
@@ -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
 
 

diff --git a/docs/make.jl b/docs/make.jl
@@ -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",
@@ -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",
@@ -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(

diff --git a/docs/pdf/Manifest.toml b/docs/pdf/Manifest.toml
@@ -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"
diff --git a/docs/pdf/Project.toml b/docs/pdf/Project.toml
@@ -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"
diff --git a/docs/pdf/make.jl b/docs/pdf/make.jl
@@ -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",
+)
diff --git a/docs/src/lib/internals/formats.md b/docs/src/lib/internals/formats.md
diff --git a/docs/src/man/other-formats.md b/docs/src/man/other-formats.md
@@ -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.
 
@@ -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.