Skip to content

Commit

Permalink
Lots of documentation
Browse files Browse the repository at this point in the history
Still WIP though.
  • Loading branch information
christopher-dG committed Sep 1, 2019
1 parent be6a8c9 commit fea66ea
Show file tree
Hide file tree
Showing 14 changed files with 369 additions and 54 deletions.
14 changes: 9 additions & 5 deletions .travis.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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;
Expand Down
6 changes: 2 additions & 4 deletions README.md
Original file line number Diff line number Diff line change
@@ -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
Expand All @@ -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")
Expand Down
5 changes: 3 additions & 2 deletions docs/make.jl
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
using Documenter
using PkgTemplates
using PkgTemplates: PkgTemplates

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

Expand Down
31 changes: 31 additions & 0 deletions docs/src/developer.md
Original file line number Diff line number Diff line change
@@ -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
```
8 changes: 0 additions & 8 deletions docs/src/index.md

This file was deleted.

67 changes: 67 additions & 0 deletions docs/src/user.md
Original file line number Diff line number Diff line change
@@ -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
```
1 change: 0 additions & 1 deletion src/PkgTemplates.jl
Original file line number Diff line number Diff line change
Expand Up @@ -35,6 +35,5 @@ abstract type Plugin end
include("template.jl")
include("generate.jl")
include("plugin.jl")
# include("interactive.jl")

end
73 changes: 65 additions & 8 deletions src/plugin.jl
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand All @@ -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.
Expand All @@ -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

Expand All @@ -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
Expand Down
Loading

0 comments on commit fea66ea

Please sign in to comment.