From 385195c6b57c2d3e018b140c9416e0bca17e430b Mon Sep 17 00:00:00 2001 From: Chris de Graaf Date: Wed, 25 Sep 2019 21:56:00 +0700 Subject: [PATCH] Improve documentation clarity --- README.md | 30 ++++++++++++++++++++++++++---- docs/make.jl | 2 +- docs/src/index.md | 15 +++------------ docs/src/migrating.md | 11 ++++++----- docs/src/user.md | 16 ++++++++++++++-- src/plugins/develop.jl | 2 +- src/plugins/documenter.jl | 8 ++++++-- src/template.jl | 2 +- 8 files changed, 58 insertions(+), 28 deletions(-) diff --git a/README.md b/README.md index f4d0acf..d2c04c3 100644 --- a/README.md +++ b/README.md @@ -7,13 +7,35 @@ **PkgTemplates creates new Julia packages in an easy, repeatable, and customizable way.** -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: +## Installation + +Install with Pkg, just like any other registered Julia package: + +```jl +pkg> add PkgTemplates # Press ']' to enter te Pkg REPL mode. +``` + +## Usage + +Creating a `Template` is as simple as: ```jl using PkgTemplates t = Template() ``` +The no-keywords constructor assumes the existence of some preexisting Git configuration (set with `git config --global`): + +- `user.name`: Your real name, e.g. John Smith. +- `user.email`: Your email address, eg. john.smith@acme.corp. +- `github.user`: Your GitHub username: e.g. john-smith. + +Once you have a `Template`, use it to generate a package: + +```jl +t("MyPkg") +``` + However, it's probably desirable to customize the template to your liking with various options and plugins: ```jl @@ -24,14 +46,14 @@ t = Template(; Codecov(), TravisCI(; x86=true), Documenter{TravisCI}(), - ], +o ], ) ``` -Once you have a template, you can create packages with ease: +You can also create a `Template` interactively by following a set of prompts: ```jl -t("MyPkg") +julia> t = Template(; interactive=true) ``` --- diff --git a/docs/make.jl b/docs/make.jl index 830e646..622e895 100644 --- a/docs/make.jl +++ b/docs/make.jl @@ -14,7 +14,7 @@ makedocs(; "Home" => "index.md", "User Guide" => "user.md", "Developer Guide" => "developer.md", - "Migrating To 0.7+" => "migrating.md", + "Migrating To PkgTemplates 0.7+" => "migrating.md", ], ) diff --git a/docs/src/index.md b/docs/src/index.md index 9e6c04a..924afa8 100644 --- a/docs/src/index.md +++ b/docs/src/index.md @@ -6,24 +6,15 @@ CurrentModule = PkgTemplates **PkgTemplates creates new Julia packages in an easy, repeatable, and customizable way.** -### Foreword: Templating vs. Template - -This documentation refers plenty to [`Template`](@ref)s, the package's main type. -But it also refers to "template files" and "text templating", which are plaintext files with placeholders to be filled with data, and the technique of filling those placeholders with data, respectively. - -These concepts should be familiar if you've used [Jinja](https://palletsprojects.com/p/jinja) or [Mustache](https://mustache.github.io) (Mustache is the particular flavour used by PkgTemplates, via [Mustache.jl](https://github.com/jverzani/Mustache.jl)). - -Please keep the difference between these two things in mind when reading this documentation! - -### Documentation +## Documentation If you're looking to **create new packages**, see the [User Guide](user.md). If you want to **create new plugins**, see the [Developer Guide](developer.md). -if you're trying to **migrate from an older version of PkgTemplates**, see [Migrating To 0.7+](migrating.md). +if you're trying to **migrate from an older version of PkgTemplates**, see [Migrating To PkgTemplates 0.7+](migrating.md). -### Index +## Index ```@index ``` diff --git a/docs/src/migrating.md b/docs/src/migrating.md index 40cc7c8..a003078 100644 --- a/docs/src/migrating.md +++ b/docs/src/migrating.md @@ -21,7 +21,7 @@ The recurring theme is "everything is a plugin now". | `ssh=true` | `plugins=[Git(; ssh=true)]` | | `manifest=true` | `plugins=[Git(; manifest=true)]` | -\* `develop=true` was the default setting. +\* `develop=true` was the default setting, but it is no longer the default in PkgTemplates 0.7+. ## Plugins @@ -55,10 +55,11 @@ Two less names to remember! Another two less names to remember! Although it's unlikely that anyone used these. -| Old | New | -| :------------------: | :---------------------------------------------------------------------------------: | -| `available_licenses` | [GitHub](https://github.com/invenia/PkgTemplates.jl/tree/master/templates/licenses) | -| `show_license` | [GitHub](https://github.com/invenia/PkgTemplates.jl/tree/master/templates/licenses) | +| Old | New | +| :------------------: | :--------------------------------------------------------------------------------------------------: | +| `available_licenses` | [View licenses on GitHub](https://github.com/invenia/PkgTemplates.jl/tree/master/templates/licenses) | +| `show_license` | [View licenses on GitHub](https://github.com/invenia/PkgTemplates.jl/tree/master/templates/licenses) | +| | | ## Custom Plugins diff --git a/docs/src/user.md b/docs/src/user.md index 5e92a15..6d34420 100644 --- a/docs/src/user.md +++ b/docs/src/user.md @@ -9,7 +9,13 @@ Pages = ["user.md"] ``` Using PkgTemplates is straightforward. -Just create a [`Template`](@ref), and call it on a package name to generate that package. +Just create a [`Template`](@ref), and call it on a package name to generate that package: + +```julia +using PkgTemplates +t = Template() +t("MyPkg") +``` ## Template @@ -22,7 +28,7 @@ Template Plugins add functionality to `Template`s. There are a number of plugins available to automate common boilerplate tasks. -### Defaults +### Default Plugins These plugins are included 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. @@ -71,6 +77,12 @@ Citation ## Custom Template Files +!!! note "Templates vs Templating" + This documentation refers plenty to [`Template`](@ref)s, the package's main type, but it also refers to "template files" and "text templating", which are plaintext files with placeholders to be filled with data, and the technique of filling those placeholders with data, respectively. + + These concepts should be familiar if you've used [Jinja](https://palletsprojects.com/p/jinja) or [Mustache](https://mustache.github.io) (Mustache is the particular flavour used by PkgTemplates, via [Mustache.jl](https://github.com/jverzani/Mustache.jl)). + Please keep the difference between these two things in mind! + Many plugins support a `file` argument or similar, which sets the path to the template file to be used for generating files. Each plugin has a sensible default that should make sense for most people, but you might have a specialized workflow that requires a totally different template file. diff --git a/src/plugins/develop.jl b/src/plugins/develop.jl index 467a82c..a06fef7 100644 --- a/src/plugins/develop.jl +++ b/src/plugins/develop.jl @@ -2,7 +2,7 @@ Develop() Adds generated packages to the current environment by `dev`ing them. -See [here](https://julialang.github.io/Pkg.jl/v1/managing-packages/#Developing-packages-1) for more details. +See the Pkg documentation [here](https://julialang.github.io/Pkg.jl/v1/managing-packages/#Developing-packages-1) for more details. """ struct Develop <: Plugin end diff --git a/src/plugins/documenter.jl b/src/plugins/documenter.jl index 0963bfc..6fb9f5c 100644 --- a/src/plugins/documenter.jl +++ b/src/plugins/documenter.jl @@ -15,6 +15,11 @@ const DOCUMENTER_DEP = PackageSpec(; Sets up documentation generation via [Documenter.jl](https://github.com/JuliaDocs/Documenter.jl). Documentation deployment depends on `T`, where `T` is some supported CI plugin, or `Nothing` to only support local documentation builds. +## Supported Type Parameters +- `TravisCI`: Deploys documentation to [GitHub Pages](https://pages.github.com) with the help of [`TravisCI`](@ref). +- `GitLabCI`: Deploys documentation to [GitLab Pages](https://pages.gitlab.com) with the help of [`GitLabCI`](@ref). +- `Nothing` (default): Does not set up documentation deployment. + ## Keyword Arguments - `make_jl::AbstractString`: Template file for `make.jl`. - `index_md::AbstractString`: Template file for `index.md`. @@ -24,8 +29,7 @@ Documentation deployment depends on `T`, where `T` is some supported CI plugin, - `makedocs_kwargs::Dict{Symbol}`: Extra keyword arguments to be inserted into `makedocs`. !!! note - If deploying documentation with Travis CI, don't forget to complete the required configuration. - See [here](https://juliadocs.github.io/Documenter.jl/stable/man/hosting/#SSH-Deploy-Keys-1). + If deploying documentation with Travis CI, don't forget to complete [the required configuration](https://juliadocs.github.io/Documenter.jl/stable/man/hosting/#SSH-Deploy-Keys-1). """ struct Documenter{T<:Union{TravisCI, GitLabCI, Nothing}} <: Plugin assets::Vector{String} diff --git a/src/template.jl b/src/template.jl index 164cbfd..d15873d 100644 --- a/src/template.jl +++ b/src/template.jl @@ -79,7 +79,7 @@ function Template(::Val{false}; kwargs...) foreach(plugins) do p if needs_username(p) T = nameof(typeof(p)) - s = "$T: Git hosting service username is required, supply user=username" + s = """$T: Git hosting service username is required, set one with keyword `user=""`""" throw(ArgumentError(s)) end end