Highlight indented method signatures in docstrings by default

CHANGELOG.md

@@ -44,6 +44,9 @@
 
 * ![Enhancement][badge-enhancement] The construction of the search index in the HTML output has been refactored to make it easier to use with other search backends in the future. The structure of the generated search index has also been modified, which can yield slightly different search results. Documenter now depends on the lightweight [JSON.jl][json-jl] package. ([#966][github-966])
 
+* ![Enhancement][badge-enhancement] Docstrings that begin with an indented code block (such as a function signature) now have that block highlighted as Julia code by default.
+  This behaviour can be disabled by passing `highlightsig=false` to `makedocs`. ([#980][github-980])
+
 * ![Bugfix][badge-bugfix] Paths in `include` calls in `@eval`, `@example`, `@repl` and `jldoctest`
   blocks are now interpreted to be relative `pwd`, which is set to the output directory of the
   resulting file. ([#941][github-941])
@@ -270,6 +273,7 @@
 [github-966]: https://github.com/JuliaDocs/Documenter.jl/pull/966
 [github-967]: https://github.com/JuliaDocs/Documenter.jl/pull/967
 [github-971]: https://github.com/JuliaDocs/Documenter.jl/pull/971
+[github-980]: https://github.com/JuliaDocs/Documenter.jl/pull/980
 
 [documenterlatex]: https://github.com/JuliaDocs/DocumenterLaTeX.jl
 [documentermarkdown]: https://github.com/JuliaDocs/DocumenterMarkdown.jl

src/Documenter.jl

@@ -63,6 +63,7 @@ export Deps, makedocs, deploydocs, hide
         doctest = true,
         modules = Module[],
         repo    = "",
+        highlightsig = true,
     )
 
 Combines markdown files and inline docstrings into an interlinked document.
@@ -149,6 +150,12 @@ For example if you are using GitLab.com, you could use
 makedocs(repo = \"https://gitlab.com/user/project/blob/{commit}{path}#{line}\")
 ```
 
+**`highlightsig`** enables or disables automatic syntax highlighting of leading, unlabeled
+code blocks in docstrings (as Julia code). For example, if your docstring begins with an
+indented code block containing the function signature, then that block would be highlighted
+as if it were a labeled Julia code block. No other code blocks are affected. This feature
+is enabled by default.
+
 # Experimental keywords
 
 In addition to standard arguments there is a set of non-finalized experimental keyword

src/Documents.jl

@@ -201,6 +201,7 @@ struct User
     sitename:: String
     authors :: String
     version :: String # version string used in the version selector by default
+    highlightsig::Bool  # assume leading unlabeled code blocks in docstrings to be Julia.
 end
 
 """
@@ -252,6 +253,7 @@ function Document(plugins = nothing;
         sitename :: AbstractString   = "",
         authors  :: AbstractString   = "",
         version :: AbstractString    = "",
+        highlightsig::Bool           = true,
         others...
     )
     Utilities.check_kwargs(others)
@@ -281,7 +283,8 @@ function Document(plugins = nothing;
         repo,
         sitename,
         authors,
-        version
+        version,
+        highlightsig
     )
     internal = Internal(
         Utilities.assetsdir(),

src/Expanders.jl

@@ -333,6 +333,9 @@ function Selectors.runner(::Type{DocsBlocks}, x, page, doc)
         docstr = Markdown.MD(map(Documenter.DocSystem.parsedoc, docs))
         docstr.meta[:results] = docs
 
+        # If the first element of the docstring is a code block, make it Julia by default.
+        doc.user.highlightsig && highlightsig!(docstr)
+
         # Generate a unique name to be used in anchors and links for the docstring.
         slug = Utilities.slugify(object)
         anchor = Anchors.add!(doc.internal.docs, object, slug, page.build)
@@ -445,6 +448,7 @@ function Selectors.runner(::Type{AutoDocsBlocks}, x, page, doc)
             end
             markdown = Markdown.MD(Documenter.DocSystem.parsedoc(docstr))
             markdown.meta[:results] = [docstr]
+            doc.user.highlightsig && highlightsig!(markdown)
             slug = Utilities.slugify(object)
             anchor = Anchors.add!(doc.internal.docs, object, slug, page.build)
             docsnode = DocsNode(markdown, anchor, object, page)
@@ -700,4 +704,14 @@ function get_new_sandbox(name::Symbol)
     return m
 end
 
+highlightsig!(x) = nothing
+function highlightsig!(md::Markdown.MD)
+    isempty(md.content) || highlightsig!(first(md.content))
+end
+function highlightsig!(code::Markdown.Code)
+    if isempty(code.language)
+        code.language = "julia"
+    end
+end
+
 end

test/runtests.jl

@@ -67,3 +67,34 @@ module MarkdownToNode
         end
     end
 end
+
+# Docstring signature syntax highlighting tests.
+module HighlightSig
+    using Test
+    import Markdown
+    import Documenter.Expanders: highlightsig!
+
+    @testset "highlightsig!" begin
+        s = """
+                foo(bar::Baz)
+            ---
+                foo(bar::Baz)
+            """
+        original = Markdown.parse(s)
+        md = Markdown.parse(s)
+        highlightsig!(md)
+        @test isempty(original.content[1].language)
+        @test md.content[1].language == "julia"
+        @test original.content[end].language == md.content[end].language
+
+        s = """
+            ```lang
+             foo(bar::Baz)
+            ```
+            """
+        original = Markdown.parse(s)
+        md = Markdown.parse(s)
+        highlightsig!(md)
+        @test original == md
+    end
+end