Lots of documentation

Still WIP though.

.travis.yml

@@ -27,11 +27,15 @@ matrix:
       julia: 1.0
     - stage: Documentation
       julia: 1.0
-      script: julia --project=docs -e '
-        using Pkg;
-        Pkg.develop(PackageSpec(; path=pwd()));
-        Pkg.instantiate();
-        include("docs/make.jl");'
+      script:
+        - git config --global user.name Your-Name
+        - git config --global user.email your-email
+        - git config --global github.user your-username
+        - julia --project=docs -e '
+            using Pkg;
+            Pkg.develop(PackageSpec(; path=pwd()));
+            Pkg.instantiate();
+            include("docs/make.jl");'
       after_success: skip
 after_success: julia -e '
   using Pkg;

README.md

@@ -1,14 +1,12 @@
 # PkgTemplates
 
 [![Stable](https://img.shields.io/badge/docs-stable-blue.svg)](https://invenia.github.io/PkgTemplates.jl/stable)
-[![Dev](https://img.shields.io/badge/docs-latest-blue.svg)](https://invenia.github.io/PkgTemplates.jl/dev)
+[![Dev](https://img.shields.io/badge/docs-dev-blue.svg)](https://invenia.github.io/PkgTemplates.jl/dev)
 [![Build Status](https://travis-ci.org/invenia/PkgTemplates.jl.svg?branch=master)](https://travis-ci.org/invenia/PkgTemplates.jl)
 [![Codecov](https://codecov.io/gh/invenia/PkgTemplates.jl/branch/master/graph/badge.svg)](https://codecov.io/gh/invenia/PkgTemplates.jl)
 
 **PkgTemplates creates new Julia packages in an easy, repeatable, and customizable way.**
 
-## Usage
-
 Assuming you have the relatively standard Git options `user.name`, `user.email` and `github.user` set up globally with `git config --global`, creating a `Template` is as simple as:
 
 ```jl
@@ -31,7 +29,7 @@ t = Template(;
 )
 ```
 
-Once you have a `Template`, yoy can createa packages with ease:
+Once you have a template, you can create packages with ease:
 
 ```jl
 t("MyPkg")

docs/make.jl

@@ -1,5 +1,5 @@
 using Documenter
-using PkgTemplates
+using PkgTemplates: PkgTemplates
 
 makedocs(;
     modules=[PkgTemplates],
@@ -11,7 +11,8 @@ makedocs(;
         assets=String[],
     ),
     pages=[
-        "Home" => "index.md",
+        "Home" => "user.md",
+        "Developer Guide" => "developer.md",
     ],
 )
 

docs/src/developer.md

@@ -0,0 +1,31 @@
+```@meta
+CurrentModule = PkgTemplates
+```
+
+# PkgTemplates Developer Guide
+
+PkgTemplates can be easily extended by adding new [`Plugin`](@ref)s.
+
+## The `Plugin` Interface
+
+```@docs
+gen_plugin
+gitignore
+badges
+Badge
+view
+user_view
+combined_view
+tags
+```
+
+## The `BasicPlugin` Interface
+
+While subtyping [`Plugin`](@ref) gives you complete freedom, it's not always necessary.
+For more constrained cases, a simpler API exists.
+
+```@docs
+BasicPlugin
+source
+destination
+```

docs/src/user.md

@@ -0,0 +1,67 @@
+```@meta
+CurrentModule = PkgTemplates
+```
+
+# PkgTemplates User Guide
+
+Using PkgTemplates is straightforward.
+Just create a [`Template`](@ref), and call it on a package name to generate that package.
+
+## Template
+
+```@docs
+Template
+```
+
+## Plugins
+
+Plugins are PkgTemplates' source of customization and extensibility.
+Add plugins to your templates to enable extra pieces of repository setup.
+
+```@docs
+Plugin
+```
+
+### Defaults
+
+These plugins are included in [`Template`](@ref)s by default.
+They can be overridden by supplying another value via the `plugins` keyword, or disabled by supplying the type via the `disable_defaults` keyword.
+
+```@docs
+Gitignore
+License
+Readme
+Tests
+```
+
+### Continuous Integration (CI)
+
+These plugins will create the configuration files of common CI services for you.
+
+```@docs
+AppVeyor
+CirrusCI
+GitLabCI
+TravisCI
+```
+
+### Code Coverage
+
+These plugins will enable code coverage reporting from CI.
+
+```@docs
+Codecov
+Coveralls
+```
+
+### Documentation
+
+```@docs
+Documenter
+```
+
+### Miscellaneous
+
+```@docs
+Citation
+```

src/PkgTemplates.jl

@@ -35,6 +35,5 @@ abstract type Plugin end
 include("template.jl")
 include("generate.jl")
 include("plugin.jl")
-# include("interactive.jl")
 
 end

src/plugin.jl

@@ -12,10 +12,16 @@ badge_order() = [
 ]
 
 """
-A simple plugin that, in general, manages a single file.
-For example, most CI services reply on one configuration file.
+A simple plugin that, in general, creates a single file.
 
-TODO: Dev guide.
+You needn't implement [`gen_plugin`](@ref) for your subtypes.
+Instead, you're left to implement a couple of much simpler functions:
+
+- [`source`](@ref)
+- [`destination`](@ref)
+
+For examples, see the plugins in the [Continuous Integration (CI)](@ref) and [Code Coverage](@ref) sections.
+For an example of a plugin that creates a file and then does some additional work, see [`Tests`](@ref).
 """
 abstract type BasicPlugin <: Plugin end
 
@@ -25,59 +31,96 @@ default_file(paths::AbstractString...) = joinpath(DEFAULTS_DIR, paths...)
 """
     view(::Plugin, ::Template, pkg::AbstractString) -> Dict{String, Any}
 
-Return the string replacements to be made for this plugin.
+Return the view to be passed to the text templating engine for this plugin.
 `pkg` is the name of the package being generated.
+
+For [`BasicPlugin`](@ref)s, this is used for both the plugin badges (see [`badges`](@ref)) and the template file (see [`source`](@ref)).
+For other [`Plugin`](@ref)s, it is used only for badges, but you can always call it yourself as part of your [`gen_plugin`](@ref) implementation.
+
+By default, an empty `Dict` is returned.
+
+!!! note
+    For more information on templating with Mustache, see the [Mustache.jl](https://github.com/jverzani/Mustache.jl) documentation.
 """
 view(::Plugin, ::Template, ::AbstractString) = Dict{String, Any}()
 
 """
     user_view(::Plugin, ::Template, pkg::AbstractString) -> Dict{String, Any}
 
-The same as [`view`](@ref), but for use only by package *users* for extension.
-TODO better explanation
+The same as [`view`](@ref), but for use by package *users* for extension.
+
+For example, suppose you were using the [`Readme`](@ref) with a custom template file that looked like this:
+
+```md
+# {{PKG}}
+
+Created on *{{TODAY}}*.
+```
+
+The [`view`](@ref) function supplies a value for `PKG`, but it does not supply a value for `TODAY`.
+Rather than override [`view`](@ref), we can implement this function to get both the default values and whatever else we need to add.
+
+```julia
+user_view(::Readme, ::Template, ::AbstractString) = Dict("TODAY" => today())
+```
+
+Values returned by this function will override those from [`view`](@ref) when the keys are the same.
 """
 user_view(::Plugin, ::Template, ::AbstractString) = Dict{String, Any}()
 
 """
     tags(::Plugin) -> Tuple{String, String}
 
 Return the tags used for Mustache templating.
+See the [`Citation`](@ref) plugin for a rare case where changing the tags is necessary.
+
+By default, the tags are `"{{"` and `"}}"`.
 """
 tags(::Plugin) = ("{{", "}}")
 
 """
     gitignore(::Plugin) -> Vector{String}
 
 Return patterns that should be added to `.gitignore`.
+These are used by the [`Gitignore`](@ref) plugin.
+
+By default, an empty list is returned.
 """
 gitignore(::Plugin) = String[]
 
 """
     badges(::Plugin) -> Union{Badge, Vector{Badge}}
 
 Return a list of [`Badge`](@ref)s, or just one, to be added to `README.md`.
+These are used by the [`Readme`](@ref) plugin to add badges to the README.
+
+By default, an empty list is returned.
 """
 badges(::Plugin) = Badge[]
 
 """
     source(::BasicPlugin) -> Union{String, Nothing}
 
-Return the path to a plugin's configuration file template, or `nothing` to indicate no file.
+Return the path to a plugin's template file, or `nothing` to indicate no file.
+
+By default, `nothing` is returned.
 """
 source(::BasicPlugin) = nothing
 
 """
     destination(::BasicPlugin) -> String
 
 Return the destination, relative to the package root, of a plugin's configuration file.
+
+This function **must** be implemented.
 """
 function destination end
 
 """
     Badge(hover::AbstractString, image::AbstractString, link::AbstractString) -> Badge
 
 Container for Markdown badge data.
-Each argument can contain placeholders.
+Each argument can contain placeholders (which will be filled in with values from [`combined_view`](@ref)).
 
 ## Arguments
 * `hover::AbstractString`: Text to appear when the mouse is hovered over the badge.
@@ -104,6 +147,11 @@ end
 
 Perform any work associated with a plugin.
 `pkg` is the name of the package being generated.
+
+For [`Plugin`](@ref)s that are not [`BasicPlugin`](@ref)s, this is the only function that really needs to be implemented.
+If you want your plugin to do anything at all during package generation, you should implement it here.
+
+You should **not** implement this function for `BasicPlugin`s.
 """
 gen_plugin(::Plugin, ::Template, ::AbstractString) = nothing
 
@@ -120,6 +168,15 @@ function render_plugin(p::BasicPlugin, t::Template, pkg::AbstractString)
     return render_file(source(p), combined_view(p, t, pkg), tags(p))
 end
 
+"""
+    combined_view(::Plugin, ::Template, pkg::AbstractString) -> Dict{String, Any}
+
+This function combines [`view`](@ref) and [`user_view`](@ref) for use in text templating.
+If you're doing manual creation (i.e. writing [`Plugin`](@ref)s that are not [`BasicPlugin`](@ref)s, then you should use this function rather than either of the former two.
+
+!!! note
+    You should **not** implement this function yourself.
+"""
 function combined_view(p::Plugin, t::Template, pkg::AbstractString)
     return merge(view(p, t, pkg), user_view(p, t, pkg))
 end