Update documentation
This commit is contained in:
Chris de Graaf
parent
c245bcd556
commit
3cf0ce6652
35
README.md
35
README.md
@ -31,18 +31,16 @@ INFO: Made initial empty commit
|
||||
INFO: Set remote origin to https://github.com/invenia/MyPkg.jl
|
||||
INFO: Staged 5 files/directories: src/, test/, REQUIRE, .gitignore, README.md
|
||||
INFO: Committed files generated by PkgTemplates
|
||||
INFO: Copying temporary package directory into /home/degraafc/.julia/v0.6/
|
||||
INFO: Moving temporary package directory into /home/degraafc/.julia/v0.6/
|
||||
INFO: Finished
|
||||
|
||||
julia> run(`ls -R $(Pkg.dir("MyPkg"))`)
|
||||
/home/degraafc/.julia/v0.6/MyPkg:
|
||||
README.md REQUIRE src test
|
||||
|
||||
/home/degraafc/.julia/v0.6/MyPkg/src:
|
||||
MyPkg.jl
|
||||
|
||||
/home/degraafc/.julia/v0.6/MyPkg/test:
|
||||
runtests.jl
|
||||
julia> cd(joinpath(t.dir, "MyPkg")); run(`git ls-tree -r --name-only HEAD`)
|
||||
.gitignore
|
||||
.travis.yml
|
||||
README.md
|
||||
REQUIRE
|
||||
src/MyPkg.jl
|
||||
test/runtests.jl
|
||||
```
|
||||
However, we can also configure a number of keyword arguments to `Template` and
|
||||
`generate`:
|
||||
@ -55,10 +53,12 @@ julia> t = Template(;
|
||||
years="2016-2017",
|
||||
dir=joinpath(ENV["HOME"], "code"),
|
||||
julia_version=v"0.5.2",
|
||||
requirements=["PkgTemplates"],
|
||||
git_config=Dict("diff.renames" => true),
|
||||
plugins=[
|
||||
TravisCI(),
|
||||
CodeCov(; config_file=nothing),
|
||||
Coveralls(),
|
||||
AppVeyor(),
|
||||
GitHubPages(; assets=[joinpath(ENV["HOME"], "invenia.css")]),
|
||||
],
|
||||
@ -72,9 +72,22 @@ INFO: Set remote origin to git@github.com:invenia/MyPkg.jl.git
|
||||
INFO: Created empty gh-pages branch
|
||||
INFO: Staged 9 files/directories: src/, test/, REQUIRE, README.md, .gitignore, LICENSE, .travis.yml, .appveyor.yml, docs/
|
||||
INFO: Committed files generated by PkgTemplates
|
||||
INFO: Copying temporary package directory into /home/degraafc/code/
|
||||
INFO: Moving temporary package directory into /home/degraafc/code/
|
||||
INFO: Finished
|
||||
WARNING: Remember to push all created branches to your remote: git push --all
|
||||
|
||||
julia> cd(joinpath(t.dir, "MyPkg")); run(`git ls-tree -r --name-only HEAD`)
|
||||
.appveyor.yml
|
||||
.gitignore
|
||||
.travis.yml
|
||||
LICENSE
|
||||
README.md
|
||||
REQUIRE
|
||||
docs/make.jl
|
||||
docs/src/assets/invenia.css
|
||||
docs/src/index.md
|
||||
src/MyPkg.jl
|
||||
test/runtests.jl
|
||||
```
|
||||
|
||||
Information on each keyword as well as plugin types can be found in the
|
||||
|
||||
@ -20,61 +20,37 @@ repeatable, and customizable way.**
|
||||
|
||||
The simplest template only requires your GitHub username.
|
||||
|
||||
```julia-repl
|
||||
julia> using PkgTemplates
|
||||
|
||||
julia> t = Template(; user="invenia")
|
||||
|
||||
julia> generate("MyPkg", t)
|
||||
INFO: Initialized git repo at /tmp/tmpvaHVki/MyPkg
|
||||
INFO: Made initial empty commit
|
||||
INFO: Set remote origin to https://github.com/invenia/MyPkg.jl
|
||||
INFO: Staged 5 files/directories: src/, test/, REQUIRE, .gitignore, README.md
|
||||
INFO: Committed files generated by PkgTemplates
|
||||
INFO: Copying temporary package directory into /home/degraafc/.julia/v0.6/
|
||||
INFO: Finished
|
||||
|
||||
julia> run(`ls -R $(Pkg.dir("MyPkg"))`)
|
||||
/home/degraafc/.julia/v0.6/MyPkg:
|
||||
README.md REQUIRE src test
|
||||
|
||||
/home/degraafc/.julia/v0.6/MyPkg/src:
|
||||
MyPkg.jl
|
||||
|
||||
/home/degraafc/.julia/v0.6/MyPkg/test:
|
||||
runtests.jl
|
||||
```@repl
|
||||
using PkgTemplates
|
||||
t = Template(; user="invenia")
|
||||
generate("MyPkg", t)
|
||||
cd(joinpath(t.dir, "MyPkg")); run(`git ls-tree -r --name-only HEAD`)
|
||||
```
|
||||
|
||||
However, we can also configure a number of keyword arguments to [`Template`](@ref) and
|
||||
[`generate`](@ref):
|
||||
|
||||
```julia-repl
|
||||
julia> t = Template(;
|
||||
```@repl
|
||||
using PkgTemplates
|
||||
t = Template(;
|
||||
user="invenia",
|
||||
license="MIT",
|
||||
authors=["Chris de Graaf", "Invenia Technical Computing Corporation"],
|
||||
years="2016-2017",
|
||||
dir=joinpath(ENV["HOME"], "code"),
|
||||
julia_version=v"0.5.2",
|
||||
requirements=["PkgTemplates"],
|
||||
git_config=Dict("diff.renames" => true),
|
||||
plugins=[
|
||||
TravisCI(),
|
||||
CodeCov(; config_file=nothing),
|
||||
Coveralls(),
|
||||
AppVeyor(),
|
||||
GitHubPages(; assets=[joinpath(ENV["HOME"], "invenia.css")]),
|
||||
],
|
||||
)
|
||||
|
||||
julia> generate("MyPkg", t; force=true, ssh=true)
|
||||
INFO: Initialized git repo at /tmp/tmpe0dWY5/MyPkg
|
||||
INFO: Applying git configuration
|
||||
INFO: Made initial empty commit
|
||||
INFO: Set remote origin to git@github.com:invenia/MyPkg.jl.git
|
||||
INFO: Created empty gh-pages branch
|
||||
INFO: Staged 9 files/directories: src/, test/, REQUIRE, README.md, .gitignore, LICENSE, .travis.yml, .appveyor.yml, docs/
|
||||
INFO: Committed files generated by PkgTemplates
|
||||
INFO: Copying temporary package directory into /home/degraafc/code/
|
||||
INFO: Finished
|
||||
WARNING: Remember to push all created branches to your remote: git push --all
|
||||
)
|
||||
generate("MyPkg", t; force=true, ssh=true)
|
||||
cd(joinpath(t.dir, "MyPkg")); run(`git ls-tree -r --name-only HEAD`)
|
||||
```
|
||||
|
||||
## Comparison to [PkgDev](https://github.com/JuliaLang/PkgDev.jl)
|
||||
|
||||
@ -18,6 +18,6 @@ show_license
|
||||
|
||||
#### `read_license`
|
||||
|
||||
````@docs
|
||||
```@docs
|
||||
read_license
|
||||
```
|
||||
|
||||
@ -5,8 +5,8 @@ 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 the
|
||||
[plugin development guide](https://invenia.github.io/PkgTemplates.jl/stable/pages/plugin_development.html).
|
||||
describes plugins that already exist; for information on writing your own plugins, see
|
||||
[Plugin Development](@ref).
|
||||
|
||||
## `TravisCI`
|
||||
|
||||
|
||||
@ -15,6 +15,12 @@ Generate a package from a template.
|
||||
# Keyword Arguments
|
||||
* `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.
|
||||
|
||||
# Notes
|
||||
The package is generated entirely in a temporary directory (`t.temp_dir`), and only moved
|
||||
into `joinpath(t.dir, pkg_name)` at the very end. In the case of an error, the temporary
|
||||
directory will contain leftovers, but the destination directory will remain untouched
|
||||
(this is especially helpful when `force=true`).
|
||||
"""
|
||||
function generate(
|
||||
pkg_name::AbstractString,
|
||||
@ -74,7 +80,7 @@ function generate(
|
||||
LibGit2.commit(repo, "Files generated by PkgTemplates")
|
||||
info("Committed files generated by PkgTemplates")
|
||||
multiple_branches = length(collect(LibGit2.GitBranchIter(repo))) > 1
|
||||
info("Copying temporary package directory into $(t.dir)/")
|
||||
info("Moving temporary package directory into $(t.dir)/")
|
||||
mv(temp_pkg_dir, pkg_dir; remove_destination=force)
|
||||
rm(t.temp_dir; recursive=true)
|
||||
info("Finished")
|
||||
|
||||
@ -1,5 +1,5 @@
|
||||
"""
|
||||
AppVeyor(; config_file::Union{AbstractString, Void}="") -> GenericPlugin
|
||||
AppVeyor(; config_file::Union{AbstractString, Void}="") -> AppVeyor
|
||||
|
||||
Add `AppVeyor` to a template's plugins to add a `.appveyor.yml` configuration file to
|
||||
generated repositories, and an appropriate badge to the README.
|
||||
|
||||
@ -1,5 +1,5 @@
|
||||
"""
|
||||
CodeCov(; config_file::Union{AbstractString, Void}="") -> GenericPlugin
|
||||
CodeCov(; config_file::Union{AbstractString, Void}="") -> CodeCov
|
||||
|
||||
Add `CodeCov` to a template's plugins to add a `.codecov.yml` configuration file to
|
||||
generated repositories, and an appropriate badge to the README. Also updates the
|
||||
|
||||
@ -1,5 +1,5 @@
|
||||
"""
|
||||
TravisCI(; config_file::Union{AbstractString, Void}="") -> GenericPlugin
|
||||
TravisCI(; config_file::Union{AbstractString, Void}="") -> TravisCI
|
||||
|
||||
Add `TravisCI` to a template's plugins to add a `.travis.yml` configuration file to
|
||||
generated repositories, and an appropriate badge to the README.
|
||||
|
||||
@ -9,7 +9,10 @@ Records common information used to generate a package.
|
||||
value. If neither is set, an `ArgumentError` is thrown.
|
||||
**This is case-sensitive for some plugins, so take care to enter it correctly.**
|
||||
* `host::AbstractString="github.com"`: URL to the code hosting service where your package
|
||||
will reside.
|
||||
will reside. Note that while hosts other than GitHub won't cause errors, they are not
|
||||
officially supported and they will cause certain plugins will produce incorrect output.
|
||||
For example, [`AppVeyor`](@ref)'s badge image will point to a GitHub-specific URL,
|
||||
regardless of the value of `host`.
|
||||
* `license::Union{AbstractString, Void}=nothing`: Name of the package license. If
|
||||
no license is specified, no license is created. [`show_license`](@ref) can be used to
|
||||
list all available licenses, or to print out a particular license's text.
|
||||
|
||||
Loading…
Reference in New Issue
Block a user