diff --git a/README.md b/README.md index b10f87e..67c77c4 100644 --- a/README.md +++ b/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 diff --git a/docs/src/index.md b/docs/src/index.md index a509927..a006947 100644 --- a/docs/src/index.md +++ b/docs/src/index.md @@ -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(; - 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", - git_config=Dict("diff.renames" => true), - plugins=[ - TravisCI(), - CodeCov(; config_file=nothing), - 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 +```@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")]), + ], +) +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) diff --git a/docs/src/pages/licenses.md b/docs/src/pages/licenses.md index 8873258..fddd256 100644 --- a/docs/src/pages/licenses.md +++ b/docs/src/pages/licenses.md @@ -18,6 +18,6 @@ show_license #### `read_license` -````@docs +```@docs read_license ``` diff --git a/docs/src/pages/plugins.md b/docs/src/pages/plugins.md index 4d31605..0caf6d1 100644 --- a/docs/src/pages/plugins.md +++ b/docs/src/pages/plugins.md @@ -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` diff --git a/src/generate.jl b/src/generate.jl index d17401f..66d391f 100644 --- a/src/generate.jl +++ b/src/generate.jl @@ -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") diff --git a/src/plugins/appveyor.jl b/src/plugins/appveyor.jl index f38104a..14df3b4 100644 --- a/src/plugins/appveyor.jl +++ b/src/plugins/appveyor.jl @@ -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. diff --git a/src/plugins/codecov.jl b/src/plugins/codecov.jl index 3e56331..001510f 100644 --- a/src/plugins/codecov.jl +++ b/src/plugins/codecov.jl @@ -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 diff --git a/src/plugins/travisci.jl b/src/plugins/travisci.jl index d7185ec..fdfb3d5 100644 --- a/src/plugins/travisci.jl +++ b/src/plugins/travisci.jl @@ -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. diff --git a/src/template.jl b/src/template.jl index 0ce7a71..b703648 100644 --- a/src/template.jl +++ b/src/template.jl @@ -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.