Add README and LICENSE (#68)

* Add README and LICENSE to make it possible to splice in
the package README.md and LICENSE.md in docstrings.

* Updates for Documenter v0.20.

Author: fredrikekre

.gitignore

@@ -3,3 +3,4 @@
 *.jl.mem
 docs/build
 docs/site
+docs/Manifest.toml

.travis.yml

@@ -19,10 +19,11 @@ after_success:
 
 jobs:
   include:
-    - stage: "Deploy docs"
+    - stage: "Documentation"
       julia: 1.0
       os: linux
       script:
-        - julia -e 'using Pkg; Pkg.add([PackageSpec("Documenter"), PackageSpec(path=pwd())])'
-        - julia docs/make.jl
+        - julia --project=docs/ -e 'using Pkg; Pkg.add(PackageSpec(path=pwd()));
+                                    Pkg.instantiate()'
+        - julia --project=docs/ docs/make.jl
       after_success: skip

docs/Project.toml

@@ -0,0 +1,5 @@
+[deps]
+Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
+
+[compat]
+Documenter = "~0.20"

docs/make.jl

@@ -3,16 +3,10 @@ using Documenter, DocStringExtensions
 makedocs(
     sitename = "DocStringExtensions.jl",
     modules = [DocStringExtensions],
-    format = :html,
     clean = false,
     pages = Any["Home" => "index.md"],
 )
 
 deploydocs(
-    target = "build",
-    deps = nothing,
-    make = nothing,
     repo = "github.com/JuliaDocs/DocStringExtensions.jl.git",
-    julia = "1.0",
 )
-

src/DocStringExtensions.jl

@@ -78,6 +78,7 @@ module DocStringExtensions
 # Exports.
 
 export @template, FIELDS, EXPORTS, METHODLIST, IMPORTS, SIGNATURES, TYPEDEF, DOCSTRING, FUNCTIONNAME
+export README, LICENSE
 
 # Includes.
 

src/abbreviations.jl

@@ -445,6 +445,60 @@ function format(::TypeDefinition, buf, doc)
     end
 end
 
+"""
+The singleton type for [`README`](@ref) abbreviations.
+"""
+struct Readme <: Abbreviation end
+"""
+    README
+
+An [`Abbreviation`](@ref) for including the package README.md.
+
+!!! note
+    The README.md file is interpreted as ["Julia flavored Markdown"]
+    (https://docs.julialang.org/en/v1/manual/documentation/#Markdown-syntax-1),
+    which has some differences compared to GitHub flavored markdown, and,
+    for example, [][] link shortcuts are not supported.
+"""
+const README = Readme()
+"""
+The singleton type for [`LICENSE`](@ref) abbreviations.
+"""
+struct License <: Abbreviation end
+"""
+    LICENSE
+
+An [`Abbreviation`](@ref) for including the package LICENSE.md.
+
+!!! note
+    The LICENSE.md file is interpreted as ["Julia flavored Markdown"]
+    (https://docs.julialang.org/en/v1/manual/documentation/#Markdown-syntax-1),
+    which has some differences compared to GitHub flavored markdown, and,
+    for example, [][] link shortcuts are not supported.
+"""
+const LICENSE = License()
+
+function format(::T, buf, doc) where T <: Union{Readme,License}
+    m = get(doc.data, :module, nothing)
+    m === nothing && return
+    path = pathof(m)
+    path === nothing && return
+    try # wrap in try/catch since we shouldn't error in case some IO operation goes wrong
+        r = T === Readme ? r"(?i)readme(?-i)" : r"(?i)license(?-i)"
+        # assume README/LICENSE is located in the root of the repo
+        root = normpath(joinpath(path, "..", ".."))
+        for file in readdir(root)
+            if occursin(r, file)
+                str = read(joinpath(root, file), String)
+                write(buf, str)
+                return
+            end
+        end
+    catch
+    end
+end
+
+
 #
 # `DocStringTemplate`
 #

test/tests.jl

@@ -230,6 +230,16 @@ end
             str = String(take!(buf))
             @test str == "\n```julia\nprimitive type BitType32 <: Real 32\n```\n\n"
         end
+
+        @testset "README/LICENSE" begin
+            doc.data = Dict(:module => DocStringExtensions)
+            DSE.format(README, buf, doc)
+            str = String(take!(buf))
+            @test occursin("*Extensions for Julia's docsystem.*", str)
+            DSE.format(LICENSE, buf, doc)
+            str = String(take!(buf))
+            @test occursin("MIT \"Expat\" License", str)
+        end
     end
     @testset "templates" begin
         let fmt = expr -> Markdown.plain(eval(:(@doc $expr)))