Merge pull request #1166 from JuliaDocs/mp/examples

Reorganize test/examples

.travis.yml

@@ -23,17 +23,23 @@ notifications:
   email: false
 
 after_success:
+  - if [ -f test/quietly.log ]; then cat test/quietly.log; fi
   - if [[ $TRAVIS_JULIA_VERSION = 1.1 ]] && [[ $TRAVIS_OS_NAME = linux ]]; then
       julia --project=coverage/ -e 'using Pkg; Pkg.instantiate();
           using Coverage; Codecov.submit(Codecov.process_folder())';
     fi
 
 jobs:
   include:
-    - stage: "Themes"
+    - stage: "Additional tests"
       script:
         - julia --project=test/themes -e 'using Pkg; Pkg.instantiate(); Pkg.develop(PackageSpec(path=pwd()))'
         - julia --project=test/themes test/themes/themes.jl
+      name: "Themes"
+    - script:
+      - julia --project=test/examples -e 'using Pkg; Pkg.instantiate(); Pkg.develop(PackageSpec(path=pwd())); Pkg.add("DocumenterMarkdown")'
+      - julia --project=test/examples test/examples/tests_latex.jl
+      name: "PDF/LaTeX backend"
     - stage: "Documentation"
       script:
         - julia --project=docs/ -e 'using Pkg; Pkg.develop(PackageSpec(path=pwd())); Pkg.instantiate()'

CHANGELOG.md

@@ -8,6 +8,10 @@
 
 * ![Enhancement][badge-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](https://ctan.org/pkg/adjustbox) LaTeX package to be available. ([#1137][github-1137])
 
+* ![Enhancement][badge-enhancement] If the TeX compilation fails for the PDF/LaTeX output, `makedocs` now throws an exception. ([#1166][github-1166])
+
+* ![Bugfix][badge-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][github-1166])
+
 * ![BREAKING][badge-breaking] Documenter no longer creates a symlink between the old `latest` url to specified `devurl`. Make sure to update links in e.g. the package readme. ([#1151][github-1151])
 
 ## Version `v0.23.4`
@@ -428,6 +432,7 @@
 [github-1151]: https://github.com/JuliaDocs/Documenter.jl/pull/1151
 [github-1152]: https://github.com/JuliaDocs/Documenter.jl/pull/1152
 [github-1153]: https://github.com/JuliaDocs/Documenter.jl/pull/1153
+[github-1166]: https://github.com/JuliaDocs/Documenter.jl/pull/1166
 
 [documenterlatex]: https://github.com/JuliaDocs/DocumenterLaTeX.jl
 [documentermarkdown]: https://github.com/JuliaDocs/DocumenterMarkdown.jl

src/Writers/LaTeXWriter.jl

@@ -134,16 +134,24 @@ function render(doc::Documents.Document, settings::LaTeX=LaTeX())
             end
             cp(STYLE, "documenter.sty")
 
-            # compile .tex and copy over the .pdf file if compile_tex return true
+            # compile .tex
             status = compile_tex(doc, settings, texfile)
-            status && cp(pdffile, joinpath(doc.user.root, doc.user.build, pdffile); force = true)
 
             # Debug: if DOCUMENTER_LATEX_DEBUG environment variable is set, copy the LaTeX
             # source files over to a directory under doc.user.root.
             if haskey(ENV, "DOCUMENTER_LATEX_DEBUG")
-                sources = cp(pwd(), mktempdir(doc.user.root), force=true)
+                dst = isempty(ENV["DOCUMENTER_LATEX_DEBUG"]) ? mktempdir(doc.user.root) :
+                    joinpath(doc.user.root, ENV["DOCUMENTER_LATEX_DEBUG"])
+                sources = cp(pwd(), dst, force=true)
                 @info "LaTeX sources copied for debugging to $(sources)"
             end
+
+            # If the build was successful, copy of the PDF to the .build directory
+            if status
+                cp(pdffile, joinpath(doc.user.root, doc.user.build, pdffile); force = true)
+            else
+                error("Compiling the .tex file failed. See logs for more information.")
+            end
         end
     end
 end
@@ -297,6 +305,10 @@ end
 ## Index, Contents, and Eval Nodes.
 
 function latex(io::IO, index::Documents.IndexNode, page, doc)
+    # Having an empty itemize block in LaTeX throws an error, so we bail early
+    # in that situation:
+    isempty(index.elements) && (_println(io); return)
+
     _println(io, "\\begin{itemize}")
     for (object, _, page, mod, cat) in index.elements
         id = string(hash(string(Utilities.slugify(object))))
@@ -310,22 +322,39 @@ function latex(io::IO, index::Documents.IndexNode, page, doc)
 end
 
 function latex(io::IO, contents::Documents.ContentsNode, page, doc)
+    # Having an empty itemize block in LaTeX throws an error, so we bail early
+    # in that situation:
+    isempty(contents.elements) && (_println(io); return)
+
     depth = 1
-    needs_end = false
     _println(io, "\\begin{itemize}")
     for (count, path, anchor) in contents.elements
         header = anchor.object
         level = Utilities.header_level(header)
         id = string(hash(string(anchor.id, "-", anchor.nth)))
-        level < depth && (_println(io, "\\end{itemize}"); needs_end = false)
-        level > depth && (_println(io, "\\begin{itemize}"); needs_end = true)
+        # If we're changing depth, we need to make sure we always print the
+        # correct number of \begin{itemize} and \end{itemize} statements.
+        if level > depth
+            for k in 1:(level - depth)
+                # if we jump by more than one level deeper we need to put empty
+                # \items in -- otherwise LaTeX will complain
+                (k >= 2) && _println(io, "\\item ~")
+                _println(io, "\\begin{itemize}")
+                depth += 1
+            end
+        elseif level < depth
+            for _ in 1:(depth - level)
+                _println(io, "\\end{itemize}")
+                depth -= 1
+            end
+        end
+        # Print the corresponding \item statement
         _print(io, "\\item \\hyperlink{", id, "}{")
         latexinline(io, header.text)
         _println(io, "}")
-        depth = level
     end
-    needs_end && _println(io, "\\end{itemize}")
-    _println(io, "\\end{itemize}")
+    # print any remaining missing \end{itemize} statements
+    for _ = 1:depth; _println(io, "\\end{itemize}"); end
     _println(io)
 end
 

test/TestUtilities.jl

@@ -4,6 +4,10 @@ using Documenter.Utilities: withoutput
 
 export @quietly
 
+const QUIETLY_LOG = joinpath(@__DIR__, "quietly.log")
+
+__init__() = isfile(QUIETLY_LOG) && rm(QUIETLY_LOG)
+
 struct QuietlyException <: Exception
     exception
     backtrace
@@ -16,6 +20,21 @@ end
 
 function _quietly(f, expr, source)
     result, success, backtrace, output = withoutput(f)
+    haskey(ENV, "DOCUMENTER_TEST_QUIETLY") && open(QUIETLY_LOG; write=true, append=true) do io
+        println(io, "@quietly: success = $(success) / $(sizeof(output)) bytes of output captured")
+        println(io, "@quietly: $(source.file):$(source.line)")
+        println(io, "@quietly: typeof(result) = ", typeof(result))
+        println(io, "@quietly: STDOUT")
+        println(io, output)
+        println(io, "@quietly: end of STDOUT")
+        if success
+            println(io, "@quietly: result =")
+            println(io, result)
+        else
+            println(io, "@quietly: result (error) =")
+            showerror(io, result, backtrace)
+        end
+    end
     if success
         printstyled("@quietly: success, $(sizeof(output)) bytes of output hidden\n"; color=:magenta)
         return result