Reduce line length of docstrings
This commit is contained in:
Chris de Graaf
parent
266a22d5c2
commit
ca51806cf6
@ -4,9 +4,9 @@
|
||||
uuid = "2a0f44e3-6c83-55bd-87e4-b1978d98bd5f"
|
||||
|
||||
[[DataAPI]]
|
||||
git-tree-sha1 = "8903f0219d3472543fc4b2f5ebaf675a07f817c0"
|
||||
git-tree-sha1 = "674b67f344687a88310213ddfa8a2b3c76cc4252"
|
||||
uuid = "9a962f9c-6df0-11e9-0e5d-c546b8b5ee8a"
|
||||
version = "1.0.1"
|
||||
version = "1.1.0"
|
||||
|
||||
[[DataValueInterfaces]]
|
||||
git-tree-sha1 = "bfc1187b79289637fa0ef6d4436ebdfe6905cbd6"
|
||||
|
||||
@ -91,7 +91,7 @@ badges(::Documenter) = [
|
||||
Badge(
|
||||
"Dev",
|
||||
"https://img.shields.io/badge/docs-dev-blue.svg",
|
||||
"https://{{{}USER}}.github.io/{{{PKG}}}.jl/dev",
|
||||
"https://{{{USER}}}.github.io/{{{PKG}}}.jl/dev",
|
||||
),
|
||||
]
|
||||
|
||||
|
||||
@ -9,7 +9,8 @@ abstract type BasicPlugin <: Plugin end
|
||||
"""
|
||||
default_file(paths::AbstractString...) -> String
|
||||
|
||||
Return a path relative to the default template file directory (`$(contractuser(TEMPLATES_DIR))`).
|
||||
Return a path relative to the default template file directory
|
||||
(`$(contractuser(TEMPLATES_DIR))`).
|
||||
"""
|
||||
default_file(paths::AbstractString...) = joinpath(TEMPLATES_DIR, paths...)
|
||||
|
||||
@ -19,8 +20,10 @@ default_file(paths::AbstractString...) = joinpath(TEMPLATES_DIR, paths...)
|
||||
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 [`hook`](@ref) implementation.
|
||||
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 [`hook`](@ref) implementation.
|
||||
|
||||
By default, an empty `Dict` is returned.
|
||||
"""
|
||||
@ -31,7 +34,8 @@ view(::Plugin, ::Template, ::AbstractString) = Dict{String, Any}()
|
||||
|
||||
The same as [`view`](@ref), but for use by package *users* for extension.
|
||||
|
||||
Values returned by this function will override those from [`view`](@ref) when the keys are the same.
|
||||
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}()
|
||||
|
||||
@ -39,7 +43,9 @@ user_view(::Plugin, ::Template, ::AbstractString) = Dict{String, Any}()
|
||||
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 file creation or text templating (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.
|
||||
If you're doing manual file creation or text templating (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
|
||||
Do not implement this function yourself!
|
||||
@ -66,7 +72,8 @@ tags(::Plugin) = "{{", "}}"
|
||||
Determines the order in which plugins are processed (higher goes first).
|
||||
The default priority (`DEFAULT_PRIORITY`), is `$DEFAULT_PRIORITY`.
|
||||
|
||||
You can implement this function per-stage (by using `::typeof(hook)`, for example), or for all stages by simply using `::Function`.
|
||||
You can implement this function per-stage (by using `::typeof(hook)`, for example),
|
||||
or for all stages by simply using `::Function`.
|
||||
"""
|
||||
priority(::Plugin, ::Function) = DEFAULT_PRIORITY
|
||||
|
||||
@ -112,12 +119,13 @@ function destination end
|
||||
Badge(hover::AbstractString, image::AbstractString, link::AbstractString)
|
||||
|
||||
Container for Markdown badge data.
|
||||
Each argument can contain placeholders (which will be filled in with values from [`combined_view`](@ref)).
|
||||
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.
|
||||
* `image::AbstractString`: URL to the image to display.
|
||||
* `link::AbstractString`: URL to go to upon clicking the badge.
|
||||
- `hover::AbstractString`: Text to appear when the mouse is hovered over the badge.
|
||||
- `image::AbstractString`: URL to the image to display.
|
||||
- `link::AbstractString`: URL to go to upon clicking the badge.
|
||||
"""
|
||||
struct Badge
|
||||
hover::String
|
||||
@ -139,7 +147,9 @@ end
|
||||
|
||||
Perform any required validation for a [`Plugin`](@ref).
|
||||
|
||||
It is preferred to do validation here instead of in [`prehook`](@ref), because this function is called at [`Template`](@ref) construction time, whereas the prehook is only run at package generation time.
|
||||
It is preferred to do validation here instead of in [`prehook`](@ref),
|
||||
because this function is called at [`Template`](@ref) construction time,
|
||||
whereas the prehook is only run at package generation time.
|
||||
"""
|
||||
validate(::Plugin, ::Template) = nothing
|
||||
|
||||
@ -147,7 +157,8 @@ validate(::Plugin, ::Template) = nothing
|
||||
prehook(::Plugin, ::Template, pkg_dir::AbstractString)
|
||||
|
||||
Stage 1 of the package generation process (the "before" stage, in general).
|
||||
At this point, `pkg_dir` is an empty directory that will eventually contain the package, and neither the [`hook`](@ref)s nor the [`posthook`](@ref)s have run.
|
||||
At this point, `pkg_dir` is an empty directory that will eventually contain the package,
|
||||
and neither the [`hook`](@ref)s nor the [`posthook`](@ref)s have run.
|
||||
|
||||
!!! note
|
||||
`pkg_dir` only stays empty until the first plugin chooses to create a file.
|
||||
@ -161,11 +172,13 @@ prehook(::Plugin, ::Template, ::AbstractString) = nothing
|
||||
Stage 2 of the package generation pipeline (the "main" stage, in general).
|
||||
At this point, the [`prehook`](@ref)s have run, but not the [`posthook`](@ref)s.
|
||||
|
||||
`pkg_dir` is the directory in which the package is being generated (so `basename(pkg_dir)` is the package name).
|
||||
`pkg_dir` is the directory in which the package is being generated
|
||||
(so `basename(pkg_dir)` is the package name).
|
||||
|
||||
!!! note
|
||||
You usually shouldn't implement this function for [`BasicPlugin`](@ref)s.
|
||||
If you do, it should probably `invoke` the generic method (otherwise, there's not much reason to subtype `BasicPlugin`).
|
||||
If you do, it should probably `invoke` the generic method
|
||||
(otherwise, there's not much reason to subtype `BasicPlugin`).
|
||||
"""
|
||||
hook(::Plugin, ::Template, ::AbstractString) = nothing
|
||||
|
||||
@ -211,7 +224,8 @@ end
|
||||
render_file(file::AbstractString view::Dict{<:AbstractString}, tags) -> String
|
||||
|
||||
Render a template file with the data in `view`.
|
||||
`tags` should be a tuple of two strings, which are the opening and closing delimiters, or `nothing` to use the default delimiters.
|
||||
`tags` should be a tuple of two strings, which are the opening and closing delimiters,
|
||||
or `nothing` to use the default delimiters.
|
||||
"""
|
||||
function render_file(file::AbstractString, view::Dict{<:AbstractString}, tags)
|
||||
return render_text(read(file, String), view, tags)
|
||||
@ -221,7 +235,8 @@ end
|
||||
render_text(text::AbstractString, view::Dict{<:AbstractString}, tags=nothing) -> String
|
||||
|
||||
Render some text with the data in `view`.
|
||||
`tags` should be a tuple of two strings, which are the opening and closing delimiters, or `nothing` to use the default delimiters.
|
||||
`tags` should be a tuple of two strings, which are the opening and closing delimiters,
|
||||
or `nothing` to use the default delimiters.
|
||||
"""
|
||||
function render_text(text::AbstractString, view::Dict{<:AbstractString}, tags=nothing)
|
||||
return tags === nothing ? render(text, view) : render(text, view; tags=tags)
|
||||
@ -231,7 +246,8 @@ end
|
||||
needs_username(::Plugin) -> Bool
|
||||
|
||||
Determine whether or not a plugin needs a Git hosting service username to function correctly.
|
||||
If you are implementing a plugin that uses the `user` field of a [`Template`](@ref), you should implement this function and return `true`.
|
||||
If you are implementing a plugin that uses the `user` field of a [`Template`](@ref),
|
||||
you should implement this function and return `true`.
|
||||
"""
|
||||
needs_username(::Plugin) = false
|
||||
|
||||
|
||||
@ -41,8 +41,10 @@ Integrates your packages with [Travis CI](https://travis-ci.com).
|
||||
- `linux::Bool`: Whether or not to run builds on Linux.
|
||||
- `osx::Bool`: Whether or not to run builds on OSX (MacOS).
|
||||
- `windows::Bool`: Whether or not to run builds on Windows.
|
||||
- `x86::Bool`: Whether or not to run builds on 32-bit systems, in addition to the default 64-bit builds.
|
||||
- `coverage::Bool`: Whether or not to publish code coverage (another code coverage plugin such as [`Codecov`](@ref) must also be included).
|
||||
- `x86::Bool`: Whether or not to run builds on 32-bit systems,
|
||||
in addition to the default 64-bit builds.
|
||||
- `coverage::Bool`: Whether or not to publish code coverage.
|
||||
Another code coverage plugin such as [`Codecov`](@ref) must also be included.
|
||||
$EXTRA_VERSIONS_DOC
|
||||
"""
|
||||
@with_kw_noshow struct TravisCI <: BasicPlugin
|
||||
@ -106,12 +108,15 @@ end
|
||||
extra_versions=$DEFAULT_CI_VERSIONS,
|
||||
)
|
||||
|
||||
Integrates your packages with [AppVeyor](https://appveyor.com) via [AppVeyor.jl](https://github.com/JuliaCI/Appveyor.jl).
|
||||
Integrates your packages with [AppVeyor](https://appveyor.com)
|
||||
via [AppVeyor.jl](https://github.com/JuliaCI/Appveyor.jl).
|
||||
|
||||
## Keyword Arguments
|
||||
- `file::AbstractString`: Template file for `.appveyor.yml`.
|
||||
- `x86::Bool`: Whether or not to run builds on 32-bit systems, in addition to the default 64-bit builds.
|
||||
- `coverage::Bool`: Whether or not to publish code coverage ([`Codecov`](@ref) must also be included).
|
||||
- `x86::Bool`: Whether or not to run builds on 32-bit systems,
|
||||
in addition to the default 64-bit builds.
|
||||
- `coverage::Bool`: Whether or not to publish code coverage.
|
||||
[`Codecov`](@ref) must also be included.
|
||||
$EXTRA_VERSIONS_DOC
|
||||
"""
|
||||
@with_kw_noshow struct AppVeyor <: BasicPlugin
|
||||
@ -156,16 +161,19 @@ end
|
||||
extra_versions=$DEFAULT_CI_VERSIONS,
|
||||
)
|
||||
|
||||
Integrates your packages with [Cirrus CI](https://cirrus-ci.org) via [CirrusCI.jl](https://github.com/ararslan/CirrusCI.jl).
|
||||
Integrates your packages with [Cirrus CI](https://cirrus-ci.org)
|
||||
via [CirrusCI.jl](https://github.com/ararslan/CirrusCI.jl).
|
||||
|
||||
## Keyword Arguments
|
||||
- `file::AbstractString`: Template file for `.cirrus.yml`.
|
||||
- `image::AbstractString`: The FreeBSD image to be used.
|
||||
- `coverage::Bool`: Whether or not to publish code coverage ([`Codecov`](@ref) must also be included).
|
||||
- `coverage::Bool`: Whether or not to publish code coverage.
|
||||
[`Codecov`](@ref) must also be included.
|
||||
$EXTRA_VERSIONS_DOC
|
||||
|
||||
!!! note
|
||||
Code coverage submission from Cirrus CI is not yet supported by [Coverage.jl](https://github.com/JuliaCI/Coverage.jl).
|
||||
Code coverage submission from Cirrus CI is not yet supported by
|
||||
[Coverage.jl](https://github.com/JuliaCI/Coverage.jl).
|
||||
"""
|
||||
@with_kw_noshow struct CirrusCI <: BasicPlugin
|
||||
file::String = default_file("cirrus.yml")
|
||||
@ -202,7 +210,7 @@ end
|
||||
extra_versions=$DEFAULT_CI_VERSIONS_NO_NIGHTLY,
|
||||
)
|
||||
|
||||
Integrates your packages with [GitLab CI](https://docs.gitlab.com/ce/ci/).
|
||||
Integrates your packages with [GitLab CI](https://docs.gitlab.com/ce/ci).
|
||||
|
||||
## Keyword Arguments
|
||||
- `file::AbstractString`: Template file for `.gitlab-ci.yml`.
|
||||
@ -270,7 +278,7 @@ Integrates your packages with [Drone CI](https://drone.io).
|
||||
For example, you might want to generate a `.drone.yml` instead of the default Starlark file.
|
||||
- `amd64::Bool`: Whether or not to run builds on AMD64.
|
||||
- `arm::Bool`: Whether or not to run builds on ARM (32-bit).
|
||||
- `arm::Bool`: Whether or not to run builds on ARM64.
|
||||
- `arm64::Bool`: Whether or not to run builds on ARM64.
|
||||
$EXTRA_VERSIONS_DOC
|
||||
|
||||
!!! note
|
||||
|
||||
@ -6,7 +6,8 @@ const COVERAGE_GITIGNORE = ["*.jl.cov", "*.jl.*.cov", "*.jl.mem"]
|
||||
Sets up code coverage submission from CI to [Codecov](https://codecov.io).
|
||||
|
||||
## Keyword Arguments
|
||||
- `file::Union{AbstractString, Nothing}`: Template file for `.codecov.yml`, or `nothing` to create no file.
|
||||
- `file::Union{AbstractString, Nothing}`: Template file for `.codecov.yml`,
|
||||
or `nothing` to create no file.
|
||||
"""
|
||||
@with_kw_noshow struct Codecov <: BasicPlugin
|
||||
file::Union{String, Nothing} = nothing
|
||||
@ -27,7 +28,8 @@ badges(::Codecov) = Badge(
|
||||
Sets up code coverage submission from CI to [Coveralls](https://coveralls.io).
|
||||
|
||||
## Keyword Arguments
|
||||
- `file::Union{AbstractString, Nothing}`: Template file for `.coveralls.yml`, or `nothing` to create no file.
|
||||
- `file::Union{AbstractString, Nothing}`: Template file for `.coveralls.yml`,
|
||||
or `nothing` to create no file.
|
||||
"""
|
||||
@with_kw_noshow struct Coveralls <: BasicPlugin
|
||||
file::Union{String, Nothing} = nothing
|
||||
|
||||
@ -2,7 +2,9 @@
|
||||
Develop()
|
||||
|
||||
Adds generated packages to the current environment by `dev`ing them.
|
||||
See the Pkg documentation [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
|
||||
|
||||
|
||||
@ -13,23 +13,29 @@ 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.
|
||||
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).
|
||||
- `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`.
|
||||
- `assets::Vector{<:AbstractString}`: Extra assets for the generated site.
|
||||
- `canonical_url::Union{Function, Nothing}`: A function to generate the documentation site's canonical URL.
|
||||
The default value will compute GitHub Pages and GitLab Pages URLs for [`TravisCI`](@ref) and [`GitLabCI`](@ref), respectively.
|
||||
- `canonical_url::Union{Function, Nothing}`: A function to generate the site's canonical URL.
|
||||
The default value will compute GitHub Pages and GitLab Pages URLs
|
||||
for [`TravisCI`](@ref) and [`GitLabCI`](@ref), respectively.
|
||||
If set to `nothing`, no canonical URL is set.
|
||||
- `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](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}
|
||||
|
||||
@ -10,7 +10,8 @@ Creates a Git repository and a `.gitignore` file.
|
||||
If left unset, HTTPS is used.
|
||||
- `manifest::Bool`: Whether or not to commit `Manifest.toml`.
|
||||
- `gpgsign::Bool`: Whether or not to sign commits with your GPG key.
|
||||
This option requires that the Git CLI is installed, and for you to have a GPG key associated with your committer identity.
|
||||
This option requires that the Git CLI is installed,
|
||||
and for you to have a GPG key associated with your committer identity.
|
||||
"""
|
||||
@with_kw_noshow struct Git <: Plugin
|
||||
ignore::Vector{String} = String[]
|
||||
|
||||
@ -5,7 +5,8 @@ Creates a license file.
|
||||
|
||||
## Keyword Arguments
|
||||
- `name::AbstractString`: Name of a license supported by PkgTemplates.
|
||||
Available licenses can be seen [here](https://github.com/invenia/PkgTemplates.jl/tree/master/templates/licenses).
|
||||
Available licenses can be seen
|
||||
[here](https://github.com/invenia/PkgTemplates.jl/tree/master/templates/licenses).
|
||||
- `path::Union{AbstractString, Nothing}`: Path to a custom license file.
|
||||
This keyword takes priority over `name`.
|
||||
- `destination::AbstractString`: File destination, relative to the repository root.
|
||||
|
||||
@ -9,10 +9,12 @@ Sets up testing for packages.
|
||||
## Keyword Arguments
|
||||
- `file::AbstractString`: Template file for `runtests.jl`.
|
||||
- `project::Bool`: Whether or not to create a new project for tests (`test/Project.toml`).
|
||||
See [here](https://julialang.github.io/Pkg.jl/v1/creating-packages/#Test-specific-dependencies-in-Julia-1.2-and-above-1) for more details.
|
||||
See [here](https://julialang.github.io/Pkg.jl/v1/creating-packages/#Test-specific-dependencies-in-Julia-1.2-and-above-1)
|
||||
for more details.
|
||||
|
||||
!!! note
|
||||
Managing test dependencies with `test/Project.toml` is only supported in Julia 1.2 and later.
|
||||
Managing test dependencies with `test/Project.toml` is only supported
|
||||
in Julia 1.2 and later.
|
||||
"""
|
||||
@with_kw_noshow struct Tests <: BasicPlugin
|
||||
file::String = default_file("test", "runtests.jl")
|
||||
|
||||
@ -21,7 +21,8 @@ A configuration used to generate packages.
|
||||
The default value comes from the global Git config (`github.user`).
|
||||
If no value is obtained, many plugins that use this value will not work.
|
||||
- `authors::Union{AbstractString, Vector{<:AbstractString}}="$(default_authors())"`: Package authors.
|
||||
Like `user`, it takes its default value from the global Git config (`user.name` and `user.email`).
|
||||
Like `user`, it takes its default value from the global Git config
|
||||
(`user.name` and `user.email`).
|
||||
|
||||
### Package Options
|
||||
- `dir::AbstractString="$(contractuser(Pkg.devdir()))"`: Directory to place packages in.
|
||||
@ -31,7 +32,8 @@ A configuration used to generate packages.
|
||||
### Template Plugins
|
||||
- `plugins::Vector{<:Plugin}=Plugin[]`: A list of [`Plugin`](@ref)s used by the template.
|
||||
- `disable_defaults::Vector{DataType}=DataType[]`: Default plugins to disable.
|
||||
The default plugins are [`ProjectFile`](@ref), [`SrcDir`](@ref), [`Tests`](@ref), [`Readme`](@ref), [`License`](@ref), and [`Git`](@ref).
|
||||
The default plugins are [`ProjectFile`](@ref), [`SrcDir`](@ref), [`Tests`](@ref),
|
||||
[`Readme`](@ref), [`License`](@ref), and [`Git`](@ref).
|
||||
To override a default plugin instead of disabling it altogether, supply it via `plugins`.
|
||||
|
||||
---
|
||||
|
||||
Loading…
Reference in New Issue
Block a user