TastyPancakes/PkgTemplates.jl
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Update docs

Browse Source 
TODO: A new asciicast.
This commit is contained in:
Chris de Graaf 2018-09-26 15:55:24 -05:00
parent 18f5e2d0c0
commit 41f4f1aa74
6 changed files with 123 additions and 60 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
.travis.yml
View File

@ -18,4 +18,6 @@ before_script:
- git config --global user.email "travis@example.com"
after_success:
- julia -e 'using Pkg; Pkg.add("Coverage"); using Coverage; CodeCov.submit(process_folder())'
# For zero-argument template example.
- git config --global github.user "travis"
- julia -e 'using Pkg; Pkg.add("Documenter"); include(joinpath("docs", "make.jl"))'

130
README.md
View File

@ -11,50 +11,73 @@ repeatable, and customizable way.**
## Installation
`PkgTemplates` is registered in
[`METADATA.jl`](https://github.com/JuliaLang/METADATA.jl), so run
`Pkg.add("PkgTemplates")` for the latest release, or
`Pkg.clone("PkgTemplates")` for the development version.
```julia
(v1.0) pkg> add PkgTemplates
```
## Usage
The simplest template only requires your GitHub username.
The simplest template requires no arguments.
```julia
julia> using PkgTemplates
julia> t = Template(; user="myusername");
julia> t = Template()
Template:
→ User: christopher-dG
→ Host: github.com
→ License: MIT (Chris de Graaf 2018)
→ Package directory: ~/.julia/dev
→ Minimum Julia version: v1.0
→ SSH remote: No
→ Plugins: None
julia> generate("MyPkg", t)
INFO: Initialized git repo at /tmp/tmpvaHVki/MyPkg
INFO: Made empty initial commit
INFO: Set remote origin to https://github.com/myusername/MyPkg.jl
INFO: Staged 6 files/directories: src/, test/, REQUIRE, README.md, .gitignore, LICENSE
INFO: Committed files generated by PkgTemplates
INFO: Moved temporary package directory into /home/degraafc/.julia/v0.6/
INFO: Finished
Generating project MyPkg:
/Users/degraafc/.julia/dev/MyPkg/Project.toml
/Users/degraafc/.julia/dev/MyPkg/src/MyPkg.jl
[ Info: Initialized git repo at /Users/degraafc/.julia/dev/MyPkg
[ Info: Set remote origin to https://github.com/myusername/MyPkg.jl
Updating registry at `~/.julia/registries/General`
Updating git-repo `https://github.com/JuliaRegistries/General.git`
Resolving package versions...
Updating `~/.julia/dev/MyPkg/Project.toml`
[8dfed614] + Test
Updating `~/.julia/dev/MyPkg/Manifest.toml`
[2a0f44e3] + Base64
[8ba89e20] + Distributed
[b77e0a4c] + InteractiveUtils
[8f399da3] + Libdl
[37e2e46d] + LinearAlgebra
[56ddb016] + Logging
[d6f4376e] + Markdown
[9a3f8284] + Random
[9e88b42a] + Serialization
[6462fe0b] + Sockets
[8dfed614] + Test
[ Info: Staged and committed 8 files/directories: src/, Project.toml, Manifest.toml, test/, REQUIRE, README.md, .gitignore, LICENSE
[ Info: Finished
julia> run(`git -C $(joinpath(t.dir, "MyPkg")) ls-tree -r --name-only HEAD`)
julia> run(`git -C $(joinpath(t.dir, "MyPkg")) ls-files`);
.gitignore
LICENSE
Manifest.toml
Project.toml
README.md
REQUIRE
src/MyPkg.jl
test/runtests.jl
```
However, we can also configure a number of keyword arguments to `Template` and
`generate`:
However, we can also configure a number of keyword arguments to `Template`:
```julia
julia> t = Template(;
user="myusername",
license="ISC",
authors=["Chris de Graaf", "Invenia Technical Computing Corporation"],
years="2016-2017",
dir=joinpath(homedir(), "code"),
julia_version=v"0.5.2",
requirements=["PkgTemplates"],
gitconfig=Dict("diff.renames" => true),
julia_version=v"0.6",
plugins=[
TravisCI(),
CodeCov(),
@ -62,30 +85,69 @@ julia> t = Template(;
AppVeyor(),
GitHubPages(),
],
);
)
Template:
→ User: myusername
→ Host: github.com
→ License: ISC (Chris de Graaf, Invenia Technical Computing Corporation 2018)
→ Package directory: ~/code
→ Minimum Julia version: v0.6
→ SSH remote: No
→ Plugins:
• AppVeyor:
→ Config file: Default
→ 0 gitignore entries
• CodeCov:
→ Config file: None
→ 3 gitignore entries: "*.jl.cov", "*.jl.*.cov", "*.jl.mem"
• Coveralls:
→ Config file: None
→ 3 gitignore entries: "*.jl.cov", "*.jl.*.cov", "*.jl.mem"
• GitHubPages:
→ 0 asset files
→ 2 gitignore entries: "/docs/build/", "/docs/site/"
• TravisCI:
→ Config file: Default
→ 0 gitignore entries
julia> generate("MyPkg", t; force=true, ssh=true)
INFO: Initialized git repo at /tmp/tmpe0dWY5/MyPkg
INFO: Applied git configuration
INFO: Made empty initial commit
INFO: Set remote origin to git@github.com:myusername/MyPkg.jl.git
INFO: Created empty gh-pages branch
INFO: Staged 9 files/directories: src/, test/, REQUIRE, README.md, .gitignore, LICENSE, docs/, .appveyor.yml, .travis.yml
INFO: Committed files generated by PkgTemplates
INFO: Moved temporary package directory into /home/degraafc/code/
INFO: Finished
WARNING: Remember to push all created branches to your remote: git push --all
julia> generate(t, "MyPkg2")
Generating project MyPkg2:
/Users/degraafc/code/MyPkg2/Project.toml
/Users/degraafc/code/MyPkg2/src/MyPkg2.jl
[ Info: Initialized git repo at /Users/degraafc/code/MyPkg2
[ Info: Set remote origin to https://github.com/myusername/MyPkg2.jl
[ Info: Created empty gh-pages branch
Resolving package versions...
Updating `~/code/MyPkg2/Project.toml`
[8dfed614] + Test
Updating `~/code/MyPkg2/Manifest.toml`
[2a0f44e3] + Base64
[8ba89e20] + Distributed
[b77e0a4c] + InteractiveUtils
[8f399da3] + Libdl
[37e2e46d] + LinearAlgebra
[56ddb016] + Logging
[d6f4376e] + Markdown
[9a3f8284] + Random
[9e88b42a] + Serialization
[6462fe0b] + Sockets
[8dfed614] + Test
[ Info: Staged and committed 11 files/directories: src/, Project.toml, Manifest.toml, test/, REQUIRE, README.md, .gitignore, LICENSE, .appveyor.yml, .travis.yml, docs/
[ Info: Finished
[ Info: Remember to push all created branches to your remote: git push --all
julia> run(`git -C $(joinpath(t.dir, "MyPkg")) ls-tree -r --name-only HEAD`)
julia> run(`git -C $(joinpath(t.dir, "MyPkg2")) ls-files`);
.appveyor.yml
.gitignore
.travis.yml
LICENSE
Manifest.toml
Project.toml
README.md
REQUIRE
docs/make.jl
docs/src/index.md
src/MyPkg.jl
src/MyPkg2.jl
test/runtests.jl
```

2
docs/make.jl
View File

@ -20,7 +20,7 @@ makedocs(;
deploydocs(;
repo="github.com/invenia/PkgTemplates.jl",
target="build",
julia="0.6",
julia="1.0",
deps=nothing,
make=nothing,
)

43
docs/src/index.md
View File

@ -11,24 +11,23 @@ repeatable, and customizable way.**
## Installation
`PkgTemplates` is registered in
[`METADATA.jl`](https://github.com/JuliaLang/METADATA.jl), so run
`Pkg.add("PkgTemplates")` for the latest release, or
`Pkg.clone("PkgTemplates")` for the development version.
```julia
(v1.0) pkg> add PkgTemplates
```
## Usage
The simplest template only requires your GitHub username.
The simplest template requires no arguments.
```@repl
using PkgTemplates
t = Template(; user="myusername");
t = Template()
generate("MyPkg", t)
run(`git -C $(joinpath(t.dir, "MyPkg")) ls-tree -r --name-only HEAD`)
run(`git -C $(joinpath(t.dir, "MyPkg")) ls-files`);
```
However, we can also configure a number of keyword arguments to
[`Template`](@ref) and [`generate`](@ref):
[`Template`](@ref):
```@repl
using PkgTemplates
@ -36,11 +35,9 @@ t = Template(;
user="myusername",
license="MIT",
authors=["Chris de Graaf", "Invenia Technical Computing Corporation"],
years="2016-2017",
dir=joinpath(homedir(), "code"),
julia_version=v"0.5.2",
requirements=["PkgTemplates"],
gitconfig=Dict("diff.renames" => true),
ssh=true,
plugins=[
TravisCI(),
CodeCov(),
@ -48,9 +45,9 @@ t = Template(;
AppVeyor(),
GitHubPages(),
],
);
generate("MyPkg", t; force=true, ssh=true)
run(`git -C $(joinpath(t.dir, "MyPkg")) ls-tree -r --name-only HEAD`)
)
generate("MyPkg2", t)
run(`git -C $(joinpath(t.dir, "MyPkg2")) ls-tree -r --name-only HEAD`);
```
If that looks like a lot of work, you can also create templates interactively
@ -65,10 +62,16 @@ but username and plugin selection.
You can also use [`generate_interactive`](@ref) to interactively generate a template and then
immediately use it to create a new package.
## Comparison to [PkgDev](https://github.com/JuliaLang/PkgDev.jl)
## Comparison to PkgDev
`PkgTemplates` is similar in functionality to `PkgDev`'s `generate` function.
However, `PkgTemplates` offers more customizability in templates and more
extensibility via plugins. For the package registration and release management
features that `PkgTemplates` lacks, you are encouraged to use
[AttoBot](https://github.com/apps/attobot) instead.
`PkgTemplates` is similar in functionality to
[`PkgDev`](https://github.com/JuliaLang/PkgDev.jl)'s `generate` function. However,
`PkgTemplates` offers more customizability in templates and more extensibility via plugins.
For the package registration and release management features that `PkgTemplates` doesn't
include, you are encouraged to use [AttoBot](https://github.com/apps/attobot) instead.
## Contributing
It's extremely easy to extend `PkgTemplates` with new plugins. To get started,
check out the
[plugin development guide](https://invenia.github.io/PkgTemplates.jl/stable/pages/plugin_development.html).

1
docs/src/pages/package_generation.md
View File

@ -24,7 +24,6 @@ generate_interactive
### Helper Functions
```@docs
gen_entrypoint
gen_tests
gen_require
gen_readme

5
src/plugin.jl
View File

@ -148,9 +148,6 @@ and [`interactive`](@ref) can be implemented using [`substitute`](@ref),
Often, the contents of the config file that your plugin generates depends on variables like
the package name, the user's username, etc. Template files (which are stored in `defaults`)
can use [here](https://github.com/jverzani/Mustache.jl)'s syntax to define replacements.
**Note**: Due to a bug in `Mustache`, conditionals can insert undesired newlines
(more detail [here](https://github.com/jverzani/Mustache.jl/issues/47)).
"""
abstract type CustomPlugin <: Plugin end
@ -171,7 +168,7 @@ A `Badge` contains the data necessary to generate a Markdown badge.
end
"""
format(b::Badge)
format(b::Badge) -> String
Return `badge`'s data formatted as a Markdown string.
"""