Add showcase page to manual (#78)

Author: mortenpi

docs/Showcase/README.md

@@ -0,0 +1,3 @@
+# Showcase.jl
+
+The demo library for DocStringExtensions.

docs/Showcase/src/Showcase.jl

@@ -0,0 +1,101 @@
+"""
+This docstring is attached to the [`Showcase`](@ref) module itself.
+
+The [`EXPORTS`](@ref) abbreviation creates a bulleted list of all the exported names:
+
+$(EXPORTS)
+
+Similarly, the [`IMPORTS`](@ref) abbreviation lists all the imported modules:
+
+$(IMPORTS)
+
+The [`README`](@ref) can be used to include the `README.md` file in a docstring. The content
+between the horizontal lines is spliced by the abbreviation:
+
+---
+
+$(README)
+
+---
+
+The [`LICENSE`](@ref) abbreviation can be used in the same way for the `LICENSE.md` file.
+"""
+module Showcase
+using DocStringExtensions
+
+"""
+This docstring is attached to an [empty function
+definitions](https://docs.julialang.org/en/v1/manual/methods/#Empty-generic-functions-1).
+The [`METHODLIST`](@ref) abbreviation allows you to list all the methods though:
+
+$(METHODLIST)
+"""
+function foo end
+
+"""
+This docstring is attached to a method that uses default values for some positional
+arguments: `foo(x::Int, y=3)`.
+
+As this effectively means that there are two different methods taking different numbers of
+arguments, the [`SIGNATURES`](@ref) abbreviation produces the following result:
+
+$(SIGNATURES)
+
+---
+
+The [`TYPEDSIGNATURES`](@ref) abbreviation can be used to also get the types of the
+variables in the function signature:
+
+$(TYPEDSIGNATURES)
+
+---
+
+The [`FUNCTIONNAME`](@ref) abbreviation can be used to directly include the name of the
+function in the docstring (e.g. here: $(FUNCTIONNAME)). This can be useful when writing your
+own type signatures:
+
+    $(FUNCTIONNAME)(x, ...)
+"""
+foo(x::Int, y=3) = nothing
+
+"""
+A different method for [`$(FUNCTIONNAME)`](@ref). [`SIGNATURES`](@ref) abbreviation:
+
+$(SIGNATURES)
+
+And the [`TYPEDSIGNATURES`](@ref) abbreviation:
+
+$(TYPEDSIGNATURES)
+"""
+foo(x::AbstractString) = nothing
+
+
+"""
+The [`TYPEDEF`](@ref) abbreviation includes the type signature:
+
+$(TYPEDEF)
+
+---
+
+The [`FIELDS`](@ref) abbreviation creates a list of all the fields of the type.
+If the fields has a docstring attached, that will also get included.
+
+$(FIELDS)
+
+---
+
+[`TYPEDFIELDS`](@ref) also adds in types for the fields:
+
+$(TYPEDFIELDS)
+"""
+struct Foobar{T <: AbstractString}
+    "Docstring for the `x` field."
+    x :: Nothing
+    y :: T # y is missing a docstring
+    "Docstring for the `z` field."
+    z :: Vector{T}
+end
+
+export foo, Foobar
+
+end

docs/make.jl

@@ -1,10 +1,19 @@
+# Add docs/lib to LOAD_PATH so that we could load the Showcase module like a library.
+let doclib = abspath(joinpath(@__DIR__, "Showcase", "src"))
+    doclib in LOAD_PATH || pushfirst!(LOAD_PATH, doclib)
+end
+
 using Documenter, DocStringExtensions
+import Showcase
 
 makedocs(
     sitename = "DocStringExtensions.jl",
-    modules = [DocStringExtensions],
+    modules = [DocStringExtensions, Showcase],
     clean = false,
-    pages = Any["Home" => "index.md"],
+    pages = Any[
+        "Home" => "index.md",
+        "Showcase" => "showcase.md",
+    ],
     format = Documenter.HTML(
         assets = ["assets/favicon.ico"],
     ),

docs/src/showcase.md

@@ -0,0 +1,28 @@
+# Showcase
+
+```@meta
+CurrentModule = Showcase
+```
+
+This page shows how the various abbreviations look.
+The docstrings themselves can be found in `docs/Showcase/src/Showcase.jl`.
+
+## Modules
+
+```@docs
+Showcase
+```
+
+## Functions and methods
+
+```@docs
+foo
+foo(::Int)
+foo(::String)
+```
+
+## Types
+
+```@docs
+Foobar
+```