Improve documentation clarity
This commit is contained in:
Chris de Graaf
parent
2b0e4bc987
commit
385195c6b5
30
README.md
30
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)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
@ -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",
|
||||
],
|
||||
)
|
||||
|
||||
|
||||
@ -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
|
||||
```
|
||||
|
||||
@ -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
|
||||
|
||||
|
||||
@ -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.
|
||||
|
||||
|
||||
@ -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
|
||||
|
||||
|
||||
@ -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}
|
||||
|
||||
@ -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="<username>"`"""
|
||||
throw(ArgumentError(s))
|
||||
end
|
||||
end
|
||||
|
||||
Loading…
Reference in New Issue
Block a user