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" - git config --global user.email "travis@example.com"
after_success: after_success:
- julia -e 'using Pkg; Pkg.add("Coverage"); using Coverage; CodeCov.submit(process_folder())' - 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"))' - 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 ## Installation
`PkgTemplates` is registered in ```julia
[`METADATA.jl`](https://github.com/JuliaLang/METADATA.jl), so run (v1.0) pkg> add PkgTemplates
`Pkg.add("PkgTemplates")` for the latest release, or ```
`Pkg.clone("PkgTemplates")` for the development version.
## Usage ## Usage
The simplest template only requires your GitHub username. The simplest template requires no arguments.
```julia ```julia
julia> using PkgTemplates 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) julia> generate("MyPkg", t)
INFO: Initialized git repo at /tmp/tmpvaHVki/MyPkg Generating project MyPkg:
INFO: Made empty initial commit /Users/degraafc/.julia/dev/MyPkg/Project.toml
INFO: Set remote origin to https://github.com/myusername/MyPkg.jl /Users/degraafc/.julia/dev/MyPkg/src/MyPkg.jl
INFO: Staged 6 files/directories: src/, test/, REQUIRE, README.md, .gitignore, LICENSE [ Info: Initialized git repo at /Users/degraafc/.julia/dev/MyPkg
INFO: Committed files generated by PkgTemplates [ Info: Set remote origin to https://github.com/myusername/MyPkg.jl
INFO: Moved temporary package directory into /home/degraafc/.julia/v0.6/ Updating registry at `~/.julia/registries/General`
INFO: Finished 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 .gitignore
LICENSE LICENSE
Manifest.toml
Project.toml
README.md README.md
REQUIRE REQUIRE
src/MyPkg.jl src/MyPkg.jl
test/runtests.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
julia> t = Template(; julia> t = Template(;
user="myusername", user="myusername",
license="ISC", license="ISC",
authors=["Chris de Graaf", "Invenia Technical Computing Corporation"], authors=["Chris de Graaf", "Invenia Technical Computing Corporation"],
years="2016-2017",
dir=joinpath(homedir(), "code"), dir=joinpath(homedir(), "code"),
julia_version=v"0.5.2", julia_version=v"0.6",
requirements=["PkgTemplates"],
gitconfig=Dict("diff.renames" => true),
plugins=[ plugins=[
TravisCI(), TravisCI(),
CodeCov(), CodeCov(),
@ -62,30 +85,69 @@ julia> t = Template(;
AppVeyor(), AppVeyor(),
GitHubPages(), 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) julia> generate(t, "MyPkg2")
INFO: Initialized git repo at /tmp/tmpe0dWY5/MyPkg Generating project MyPkg2:
INFO: Applied git configuration /Users/degraafc/code/MyPkg2/Project.toml
INFO: Made empty initial commit /Users/degraafc/code/MyPkg2/src/MyPkg2.jl
INFO: Set remote origin to git@github.com:myusername/MyPkg.jl.git [ Info: Initialized git repo at /Users/degraafc/code/MyPkg2
INFO: Created empty gh-pages branch [ Info: Set remote origin to https://github.com/myusername/MyPkg2.jl
INFO: Staged 9 files/directories: src/, test/, REQUIRE, README.md, .gitignore, LICENSE, docs/, .appveyor.yml, .travis.yml [ Info: Created empty gh-pages branch
INFO: Committed files generated by PkgTemplates Resolving package versions...
INFO: Moved temporary package directory into /home/degraafc/code/ Updating `~/code/MyPkg2/Project.toml`
INFO: Finished [8dfed614] + Test
WARNING: Remember to push all created branches to your remote: git push --all 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 .appveyor.yml
.gitignore .gitignore
.travis.yml .travis.yml
LICENSE LICENSE
Manifest.toml
Project.toml
README.md README.md
REQUIRE REQUIRE
docs/make.jl docs/make.jl
docs/src/index.md docs/src/index.md
src/MyPkg.jl src/MyPkg2.jl
test/runtests.jl test/runtests.jl
``` ```

2
docs/make.jl
View File

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

43
docs/src/index.md
View File

@ -11,24 +11,23 @@ repeatable, and customizable way.**
## Installation ## Installation
`PkgTemplates` is registered in ```julia
[`METADATA.jl`](https://github.com/JuliaLang/METADATA.jl), so run (v1.0) pkg> add PkgTemplates
`Pkg.add("PkgTemplates")` for the latest release, or ```
`Pkg.clone("PkgTemplates")` for the development version.
## Usage ## Usage
The simplest template only requires your GitHub username. The simplest template requires no arguments.
```@repl ```@repl
using PkgTemplates using PkgTemplates
t = Template(; user="myusername"); t = Template()
generate("MyPkg", t) 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 However, we can also configure a number of keyword arguments to
[`Template`](@ref) and [`generate`](@ref): [`Template`](@ref):
```@repl ```@repl
using PkgTemplates using PkgTemplates
@ -36,11 +35,9 @@ t = Template(;
user="myusername", user="myusername",
license="MIT", license="MIT",
authors=["Chris de Graaf", "Invenia Technical Computing Corporation"], authors=["Chris de Graaf", "Invenia Technical Computing Corporation"],
years="2016-2017",
dir=joinpath(homedir(), "code"), dir=joinpath(homedir(), "code"),
julia_version=v"0.5.2", julia_version=v"0.5.2",
requirements=["PkgTemplates"], ssh=true,
gitconfig=Dict("diff.renames" => true),
plugins=[ plugins=[
TravisCI(), TravisCI(),
CodeCov(), CodeCov(),
@ -48,9 +45,9 @@ t = Template(;
AppVeyor(), AppVeyor(),
GitHubPages(), GitHubPages(),
], ],
); )
generate("MyPkg", t; force=true, ssh=true) generate("MyPkg2", t)
run(`git -C $(joinpath(t.dir, "MyPkg")) ls-tree -r --name-only HEAD`) 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 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 You can also use [`generate_interactive`](@ref) to interactively generate a template and then
immediately use it to create a new package. 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. `PkgTemplates` is similar in functionality to
However, `PkgTemplates` offers more customizability in templates and more [`PkgDev`](https://github.com/JuliaLang/PkgDev.jl)'s `generate` function. However,
extensibility via plugins. For the package registration and release management `PkgTemplates` offers more customizability in templates and more extensibility via plugins.
features that `PkgTemplates` lacks, you are encouraged to use For the package registration and release management features that `PkgTemplates` doesn't
[AttoBot](https://github.com/apps/attobot) instead. 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 ### Helper Functions
```@docs ```@docs
gen_entrypoint
gen_tests gen_tests
gen_require gen_require
gen_readme 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 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`) 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. 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 abstract type CustomPlugin <: Plugin end
@ -171,7 +168,7 @@ A `Badge` contains the data necessary to generate a Markdown badge.
end end
""" """
format(b::Badge) format(b::Badge) -> String
Return `badge`'s data formatted as a Markdown string. Return `badge`'s data formatted as a Markdown string.
""" """