From d075ff678e4f0cc7ba7ae74cf24bcad79c17e009 Mon Sep 17 00:00:00 2001 From: Chris de Graaf Date: Fri, 1 Dec 2017 12:12:37 +0000 Subject: [PATCH] Update/reorganize docs --- docs/src/pages/licenses.md | 11 +--------- docs/src/pages/package_generation.md | 28 +----------------------- docs/src/pages/plugin_development.md | 5 +++-- docs/src/pages/plugins.md | 32 ++++++---------------------- src/PkgTemplates.jl | 21 ++++++++++++++++-- src/generate.jl | 4 +++- src/licenses.jl | 4 ++-- src/plugin.jl | 2 +- src/plugins/githubpages.jl | 4 ++-- 9 files changed, 38 insertions(+), 73 deletions(-) diff --git a/docs/src/pages/licenses.md b/docs/src/pages/licenses.md index ab2a185..bf6b886 100644 --- a/docs/src/pages/licenses.md +++ b/docs/src/pages/licenses.md @@ -8,21 +8,12 @@ CurrentModule = PkgTemplates are available for use with `PkgTemplates`, but if you see that one is missing, don't hesitate to open an issue or PR. -## `available_licenses` - ```@docs available_licenses -``` - -## `show_license` - -```@docs show_license ``` -## Helper Functions - -#### `read_license` +### Helper Functions ```@docs read_license diff --git a/docs/src/pages/package_generation.md b/docs/src/pages/package_generation.md index d6ad6fb..7696799 100644 --- a/docs/src/pages/package_generation.md +++ b/docs/src/pages/package_generation.md @@ -21,39 +21,13 @@ generate generate_interactive ``` -## Helper Functions - -#### `gen_entrypoint` +### Helper Functions ```@docs gen_entrypoint -``` - -#### `gen_tests` - -```@docs gen_tests -``` - -#### `gen_require` - -```@docs gen_require -``` - -#### `gen_readme` - -```@docs gen_readme -``` - -#### gen_gitignore - -```@docs gen_gitignore -``` - -#### gen_license -```@docs gen_license ``` diff --git a/docs/src/pages/plugin_development.md b/docs/src/pages/plugin_development.md index 8b76ccc..31aa992 100644 --- a/docs/src/pages/plugin_development.md +++ b/docs/src/pages/plugin_development.md @@ -7,8 +7,9 @@ CurrentModule = PkgTemplates The best and easiest way to contribute to `PkgTemplates` is to write new plugins. -There are two types of plugins: [`GenericPlugin`](@ref)s and -[`CustomPlugin`](@ref)s. +```@docs +Plugin +``` ## Generic Plugins diff --git a/docs/src/pages/plugins.md b/docs/src/pages/plugins.md index b8ff55a..57d1ab9 100644 --- a/docs/src/pages/plugins.md +++ b/docs/src/pages/plugins.md @@ -4,48 +4,28 @@ CurrentModule = PkgTemplates # Plugins -Plugins are the driver for `PkgTemplates`'s customization and extension. This -page describes plugins that already exist; for information on writing your -own plugins, see [Plugin Development](@ref). +Plugins are the secret sauce behing `PkgTemplates`'s customization and extension. This page +describes plugins that already exist; for information on writing your own plugins, see +[Plugin Development](@ref). -## `TravisCI` +## Continuous Integration (CI) ```@docs TravisCI -``` - -## `AppVeyor` - -```@docs AppVeyor -``` - -## `GitLabCI` - -```@docs GitLabCI ``` -## `CodeCov` +## Code Coverage ```@docs CodeCov -``` - -## `Coveralls` - -```@docs Coveralls ``` -## `Documenter` +## Documentation ```@docs Documenter -``` - -## `GitHubPages` - -```@docs GitHubPages ``` diff --git a/src/PkgTemplates.jl b/src/PkgTemplates.jl index 876b7e0..b7bfd96 100644 --- a/src/PkgTemplates.jl +++ b/src/PkgTemplates.jl @@ -6,10 +6,27 @@ using Mustache using TerminalMenus using URIParser -export generate, interactive_template, generate_interactive, show_license, - available_licenses, Template, GitHubPages, AppVeyor, TravisCI, GitLabCI, CodeCov, +export + # Template/package generation. + Template, + generate, + interactive_template, + generate_interactive, + # Licenses. + show_license, + available_licenses, + # Plugins. + GitHubPages, + AppVeyor, + TravisCI, + GitLabCI, + CodeCov, Coveralls +""" +A plugin to be added to a [`Template`](@ref), which adds some functionality or integration. +New plugins should almost always extend [`GenericPlugin`](@ref) or [`CustomPlugin`](@ref). +""" abstract type Plugin end include("licenses.jl") diff --git a/src/generate.jl b/src/generate.jl index 2169cac..4c3632c 100644 --- a/src/generate.jl +++ b/src/generate.jl @@ -4,6 +4,7 @@ t::Template; force::Bool=false, ssh::Bool=false, + backup_dir::AbstractString="", ) -> Void Generate a package named `pkg_name` from `template`. @@ -12,7 +13,8 @@ Generate a package named `pkg_name` from `template`. * `force::Bool=false`: Whether or not to overwrite old packages with the same name. * `ssh::Bool=false`: Whether or not to use SSH for the remote. * `backup_dir::AbstractString=""`: Directory in which to store the generated package if - `t.dir` is not a valid directory. If left unset, a temporary directory will be created. + `t.dir` is not a valid directory. If left unset, a temporary directory will be created + (this keyword is mostly for internal usage). # Notes The package is generated entirely in a temporary directory and only moved into diff --git a/src/licenses.jl b/src/licenses.jl index c7952c3..27e86b5 100644 --- a/src/licenses.jl +++ b/src/licenses.jl @@ -22,7 +22,7 @@ available_licenses() = available_licenses(STDOUT) """ show_license([io::IO], license::AbstractString) -> Void -Print the text of `license`. +Print the text of `license`. Errors if the license is not found. """ show_license(io::IO, license::AbstractString) = println(io, read_license(license)) show_license(license::AbstractString) = show_license(STDOUT, license) @@ -30,7 +30,7 @@ show_license(license::AbstractString) = show_license(STDOUT, license) """ read_license(license::AbstractString) -> String -Returns the contents of `license`. Errors if it is not found. Use +Returns the contents of `license`. Errors if the license is not found. Use [`available_licenses`](@ref) to view available licenses. """ function read_license(license::AbstractString) diff --git a/src/plugin.jl b/src/plugin.jl index 47a7c6a..14589d5 100644 --- a/src/plugin.jl +++ b/src/plugin.jl @@ -88,7 +88,7 @@ pattern. They can implement [`gen_plugin`](@ref), [`badges`](@ref), and plugin::MyPlugin, template::Template, dir::AbstractString, - pkg_name::AbstractString + pkg_name::AbstractString, ) if plugin.lucky text = substitute( diff --git a/src/plugins/githubpages.jl b/src/plugins/githubpages.jl index 015ae25..f4cd481 100644 --- a/src/plugins/githubpages.jl +++ b/src/plugins/githubpages.jl @@ -1,12 +1,12 @@ """ GitHubPages(; assets::Vector{<:AbstractString}=String[]) -> GitHubPages -Add `GitHubPages` to a template's plugins to add [Documenter](@ref) support via GitHub +Add `GitHubPages` to a template's plugins to add [`Documenter`](@ref) support via GitHub Pages, including automatic uploading of documentation from [`TravisCI`](@ref). Also adds appropriate badges to the README, and updates the `.gitignore` accordingly. # Keyword Arguments -* `assets::Vector{String}=String[]`: Array of paths to Documenter asset files. +* `assets::Vector{<:AbstractString}=String[]`: Array of paths to Documenter asset files. """ @auto_hash_equals struct GitHubPages <: Documenter gitignore::Vector{AbstractString}