Merge pull request #221 from JuliaDocs/mp/backports

Backport #217, #218, #220 to v0.3

REQUIRE

@@ -1,3 +1,3 @@
 julia 0.4
 Compat 0.8
-DocStringExtensions 0.1
+DocStringExtensions 0.2

assets/html/style.css

@@ -57,6 +57,10 @@ h4, h5, h6 {
     margin: 1em 0;
 }
 
+img {
+    max-width: 100%;
+}
+
 table {
     border-collapse: collapse;
     margin: 1em 0;
@@ -101,6 +105,28 @@ pre code {
     background-color: initial;
 }
 
+/* Headers in admonitions and docstrings */
+.admonition h1,
+article section.docstring h1 {
+    font-size: 1.25em;
+}
+
+.admonition h2,
+article section.docstring h2 {
+    font-size: 1.10em;
+}
+
+.admonition h3,
+.admonition h4,
+.admonition h5,
+.admonition h6,
+article section.docstring h3,
+article section.docstring h4,
+article section.docstring h5,
+article section.docstring h6 {
+    font-size: 1em;
+}
+
 /* Navigation */
 nav.toc {
     /* TODO: would be nice to have the navigation fixed, but the simple

docs/src/man/guide.md

@@ -280,14 +280,37 @@ user-readable format for distribution.
 While in principle any Markdown parser would do (as long as it supports the required
 Markdown extensions), the Python-based [MkDocs](http://www.mkdocs.org/) is usually used
 to convert the Markdown files into a set of HTML pages.
-See [Hosting Documentation](@ref) for further information on configuring `mkdocs` for Documenter.
+See [Hosting Documentation](@ref) for further information on configuring MkDocs for Documenter.
 
 !!! note "Native HTML output"
     There is experimental support for native HTML output in Documenter.
     It can be enabled by passing the `format = Documenter.Formats.HTML` option to
-    [`makedocs`](@ref). An example `make.jl` can be found under `test/html/`.
+    [`makedocs`](@ref). It also requires the `pages` and `sitename` options.
+    `make.jl` should then look something like
+    ```julia
+    makedocs(
+        ...,
+        format = Documenter.Formats.HTML,
+        sitename = "Package name",
+        pages = [
+            "page.md",
+            "Page title" => "page2.md",
+            "Subsection" => [
+                ...
+            ]
+        ]
+    )
+    ```
+    Since Documenter's docs are already built using HTML output, a fully working
+    example of the configuration can be found in `docs/make.jl`.
 
     It is still under development, may contain bugs, and undergo changes.
     However, any feedback is very welcome and early adopters are encouraged to try it out.
     Issues and suggestions should be posted to
     [Documenter.jl's issue tracker](https://github.com/JuliaDocs/Documenter.jl/issues).
+
+    # Additional `makedocs` options for HTML output
+    **`sitename`** is the site's title displayed in the title bar and at the top
+    of the navigation menu.
+
+    **`pages`** defines the hierarchy of the navigation menu.

src/Writers/HTMLWriter.jl

@@ -590,6 +590,15 @@ end
 # mdconvert
 # ------------------------------------------------------------------------------
 
+md_block_nodes = [Markdown.MD, Markdown.BlockQuote, Markdown.List]
+if isdefined(Base.Markdown, :Admonition) push!(md_block_nodes, Markdown.Admonition) end
+
+"""
+[`MDBlockContext`](@ref) is a union of all the Markdown nodes whose children should
+be blocks. It can be used to dispatch on all the block-context nodes at once.
+"""
+typealias MDBlockContext Union{md_block_nodes...}
+
 """
 Convert a markdown object to a `DOM.Node` object.
 
@@ -607,7 +616,7 @@ mdconvert(b::Markdown.BlockQuote, parent) = Tag(:blockquote)(mdconvert(b.content
 
 mdconvert(b::Markdown.Bold, parent) = Tag(:strong)(mdconvert(b.text, parent))
 
-function mdconvert(c::Markdown.Code, parent::Markdown.MD)
+function mdconvert(c::Markdown.Code, parent::MDBlockContext)
     @tags pre code
     language = isempty(c.language) ? "none" : c.language
     pre(code[".language-$(language)"](c.code))
@@ -622,7 +631,7 @@ mdconvert(i::Markdown.Image, parent) = Tag(:img)[:src => i.url, :alt => i.alt]
 
 mdconvert(i::Markdown.Italic, parent) = Tag(:em)(mdconvert(i.text, i))
 
-mdconvert(m::Markdown.LaTeX, ::Markdown.MD)   = Tag(:div)(string("\\[", m.formula, "\\]"))
+mdconvert(m::Markdown.LaTeX, ::MDBlockContext)   = Tag(:div)(string("\\[", m.formula, "\\]"))
 mdconvert(m::Markdown.LaTeX, parent) = Tag(:span)(string('$', m.formula, '$'))
 
 mdconvert(::Markdown.LineBreak, parent) = Tag(:br)()