4 lines
60 KiB
JavaScript
4 lines
60 KiB
JavaScript
var documenterSearchIndex = {"docs":
|
|
[{"location":"developer/#","page":"Developer Guide","title":"Developer Guide","text":"CurrentModule = PkgTemplates","category":"page"},{"location":"developer/#PkgTemplates-Developer-Guide-1","page":"Developer Guide","title":"PkgTemplates Developer Guide","text":"","category":"section"},{"location":"developer/#","page":"Developer Guide","title":"Developer Guide","text":"Pages = [\"developer.md\"]","category":"page"},{"location":"developer/#","page":"Developer Guide","title":"Developer Guide","text":"PkgTemplates can be easily extended by adding new Plugins.","category":"page"},{"location":"developer/#","page":"Developer Guide","title":"Developer Guide","text":"There are two types of plugins: Plugin and BasicPlugin.","category":"page"},{"location":"developer/#","page":"Developer Guide","title":"Developer Guide","text":"Plugin\nBasicPlugin","category":"page"},{"location":"developer/#PkgTemplates.Plugin","page":"Developer Guide","title":"PkgTemplates.Plugin","text":"Plugins are PkgTemplates' source of customization and extensibility. Add plugins to your Templates to enable extra pieces of repository setup.\n\nWhen implementing a new plugin, subtype this type to have full control over its behaviour.\n\n\n\n\n\n","category":"type"},{"location":"developer/#PkgTemplates.BasicPlugin","page":"Developer Guide","title":"PkgTemplates.BasicPlugin","text":"A simple plugin that, in general, creates a single file.\n\n\n\n\n\n","category":"type"},{"location":"developer/#Template-Package-Creation-Pipeline-1","page":"Developer Guide","title":"Template + Package Creation Pipeline","text":"","category":"section"},{"location":"developer/#","page":"Developer Guide","title":"Developer Guide","text":"The Template constructor basically does this:","category":"page"},{"location":"developer/#","page":"Developer Guide","title":"Developer Guide","text":"- extract values from keyword arguments\n- create a Template from the values\n- for each plugin:\n - validate plugin against the template","category":"page"},{"location":"developer/#","page":"Developer Guide","title":"Developer Guide","text":"The plugin validation step uses the validate function. It lets us catch mistakes before we try to generate packages.","category":"page"},{"location":"developer/#","page":"Developer Guide","title":"Developer Guide","text":"validate","category":"page"},{"location":"developer/#PkgTemplates.validate","page":"Developer Guide","title":"PkgTemplates.validate","text":"validate(::Plugin, ::Template)\n\nPerform any required validation for a Plugin.\n\nIt is preferred to do validation here instead of in prehook, because this function is called at Template construction time, whereas the prehook is only run at package generation time.\n\n\n\n\n\n","category":"function"},{"location":"developer/#","page":"Developer Guide","title":"Developer Guide","text":"The package generation process looks like this:","category":"page"},{"location":"developer/#","page":"Developer Guide","title":"Developer Guide","text":"- create empty directory for the package\n- for each plugin, ordered by priority:\n - run plugin prehook\n- for each plugin, ordered by priority:\n - run plugin hook\n- for each plugin, ordered by priority:\n - run plugin posthook","category":"page"},{"location":"developer/#","page":"Developer Guide","title":"Developer Guide","text":"As you can tell, plugins play a central role in setting up a package.","category":"page"},{"location":"developer/#","page":"Developer Guide","title":"Developer Guide","text":"The three main entrypoints for plugins to do work are the prehook, the hook, and the posthook. As the names might imply, they basically mean \"before the main stage\", \"the main stage\", and \"after the main stage\", respectively.","category":"page"},{"location":"developer/#","page":"Developer Guide","title":"Developer Guide","text":"Each stage is basically identical, since the functions take the exact same arguments. However, the multiple stages allow us to depend on artifacts of the previous stages. For example, the Git plugin uses posthook to commit all generated files, but it wouldn't make sense to do that before the files are generated.","category":"page"},{"location":"developer/#","page":"Developer Guide","title":"Developer Guide","text":"But what about dependencies within the same stage? In this case, we have priority to define which plugins go when. The Git plugin also uses this function to lower its posthook's priority, so that even if other plugins generate files in their posthooks, they still get committed (provided that those plugins didn't set an even lower priority).","category":"page"},{"location":"developer/#","page":"Developer Guide","title":"Developer Guide","text":"prehook\nhook\nposthook\npriority","category":"page"},{"location":"developer/#PkgTemplates.prehook","page":"Developer Guide","title":"PkgTemplates.prehook","text":"prehook(::Plugin, ::Template, pkg_dir::AbstractString)\n\nStage 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 hooks nor the posthooks have run.\n\nnote: Note\npkg_dir only stays empty until the first plugin chooses to create a file. See also: priority.\n\n\n\n\n\n","category":"function"},{"location":"developer/#PkgTemplates.hook","page":"Developer Guide","title":"PkgTemplates.hook","text":"hook(::Plugin, ::Template, pkg_dir::AbstractString)\n\nStage 2 of the package generation pipeline (the \"main\" stage, in general). At this point, the prehooks have run, but not the posthooks.\n\npkg_dir is the directory in which the package is being generated (so basename(pkg_dir) is the package name).\n\nnote: Note\nYou usually shouldn't implement this function for BasicPlugins. If you do, it should probably invoke the generic method (otherwise, there's not much reason to subtype BasicPlugin).\n\n\n\n\n\n","category":"function"},{"location":"developer/#PkgTemplates.posthook","page":"Developer Guide","title":"PkgTemplates.posthook","text":"posthook(::Plugin, ::Template, pkg_dir::AbstractString)\n\nStage 3 of the package generation pipeline (the \"after\" stage, in general). At this point, both the prehooks and hooks have run.\n\n\n\n\n\n","category":"function"},{"location":"developer/#PkgTemplates.priority","page":"Developer Guide","title":"PkgTemplates.priority","text":"priority(::Plugin, ::Union{typeof(prehook), typeof(hook), typeof(posthook)}) -> Int\n\nDetermines the order in which plugins are processed (higher goes first). The default priority (DEFAULT_PRIORITY), is 1000.\n\nYou can implement this function per-stage (by using ::typeof(hook), for example), or for all stages by simply using ::Function.\n\n\n\n\n\n","category":"function"},{"location":"developer/#Plugin-Walkthrough-1","page":"Developer Guide","title":"Plugin Walkthrough","text":"","category":"section"},{"location":"developer/#","page":"Developer Guide","title":"Developer Guide","text":"Concrete types that subtype Plugin directly are free to do almost anything. To understand how they're implemented, let's look at simplified versions of two plugins: Documenter to explore templating, and Git to further clarify the multi-stage pipeline.","category":"page"},{"location":"developer/#Example:-Documenter-1","page":"Developer Guide","title":"Example: Documenter","text":"","category":"section"},{"location":"developer/#","page":"Developer Guide","title":"Developer Guide","text":"@with_kw_noshow struct Documenter <: Plugin\n make_jl::String = default_file(\"docs\", \"make.jl\") <- \"Path to make.jl template\"\n index_md::String = default_file(\"docs\", \"src\", \"index.md\") <- \"Path to index.md template\"\nend\n\ngitignore(::Documenter) = [\"/docs/build/\"]\n\nbadges(::Documenter) = [\n Badge(\n \"Stable\",\n \"https://img.shields.io/badge/docs-stable-blue.svg\",\n \"https://{{{USER}}}.github.io/{{{PKG}}}.jl/stable\",\n ),\n Badge(\n \"Dev\",\n \"https://img.shields.io/badge/docs-dev-blue.svg\",\n \"https://{{{USER}}}.github.io/{{{PKG}}}.jl/dev\",\n ),\n]\n\nview(p::Documenter, t::Template, pkg::AbstractString) = Dict(\n \"AUTHORS\" => join(t.authors, \", \"),\n \"PKG\" => pkg,\n \"REPO\" => \"$(t.host)/$(t.user)/$pkg.jl\",\n \"USER\" => t.user,\n)\n\nfunction hook(p::Documenter, t::Template, pkg_dir::AbstractString)\n pkg = basename(pkg_dir)\n docs_dir = joinpath(pkg_dir, \"docs\")\n\n make = render_file(p.make_jl, combined_view(p, t, pkg), tags(p))\n gen_file(joinpath(docs_dir, \"make.jl\"), make)\n \n index = render_file(p.index_md, combined_view(p, t, pkg), tags(p))\n gen_file(joinpath(docs_dir, \"src\", \"index.md\"), index)\n\n # What this function does is not relevant here.\n create_documentation_project()\nend","category":"page"},{"location":"developer/#","page":"Developer Guide","title":"Developer Guide","text":"The @with_kw_noshow macro defines keyword constructors for us. Inside of our struct definition, we're using default_file to refer to files in this repository.","category":"page"},{"location":"developer/#","page":"Developer Guide","title":"Developer Guide","text":"default_file","category":"page"},{"location":"developer/#PkgTemplates.default_file","page":"Developer Guide","title":"PkgTemplates.default_file","text":"default_file(paths::AbstractString...) -> String\n\nReturn a path relative to the default template file directory (~/build/invenia/PkgTemplates.jl/templates).\n\n\n\n\n\n","category":"function"},{"location":"developer/#","page":"Developer Guide","title":"Developer Guide","text":"The first method we implement for Documenter is gitignore, so that packages created with this plugin ignore documentation build artifacts.","category":"page"},{"location":"developer/#","page":"Developer Guide","title":"Developer Guide","text":"gitignore","category":"page"},{"location":"developer/#PkgTemplates.gitignore","page":"Developer Guide","title":"PkgTemplates.gitignore","text":"gitignore(::Plugin) -> Vector{String}\n\nReturn patterns that should be added to .gitignore. These are used by the Git plugin.\n\nBy default, an empty list is returned.\n\n\n\n\n\n","category":"function"},{"location":"developer/#","page":"Developer Guide","title":"Developer Guide","text":"Second, we implement badges to add a couple of badges to new packages' README files.","category":"page"},{"location":"developer/#","page":"Developer Guide","title":"Developer Guide","text":"badges\nBadge","category":"page"},{"location":"developer/#PkgTemplates.badges","page":"Developer Guide","title":"PkgTemplates.badges","text":"badges(::Plugin) -> Union{Badge, Vector{Badge}}\n\nReturn a list of Badges, or just one, to be added to README.md. These are used by the Readme plugin to add badges to the README.\n\nBy default, an empty list is returned.\n\n\n\n\n\n","category":"function"},{"location":"developer/#PkgTemplates.Badge","page":"Developer Guide","title":"PkgTemplates.Badge","text":"Badge(hover::AbstractString, image::AbstractString, link::AbstractString)\n\nContainer for Markdown badge data. Each argument can contain placeholders, which will be filled in with values from combined_view.\n\nArguments\n\nhover::AbstractString: Text to appear when the mouse is hovered over the badge.\nimage::AbstractString: URL to the image to display.\nlink::AbstractString: URL to go to upon clicking the badge.\n\n\n\n\n\n","category":"type"},{"location":"developer/#","page":"Developer Guide","title":"Developer Guide","text":"These two functions, gitignore and badges, are currently the only \"special\" functions for cross-plugin interactions. In other cases, you can still access the Template's plugins to depend on the presence/properties of other plugins, although that's less powerful.","category":"page"},{"location":"developer/#","page":"Developer Guide","title":"Developer Guide","text":"Third, we implement view, which is used to fill placeholders in badges and rendered files.","category":"page"},{"location":"developer/#","page":"Developer Guide","title":"Developer Guide","text":"view","category":"page"},{"location":"developer/#PkgTemplates.view","page":"Developer Guide","title":"PkgTemplates.view","text":"view(::Plugin, ::Template, pkg::AbstractString) -> Dict{String, Any}\n\nReturn the view to be passed to the text templating engine for this plugin. pkg is the name of the package being generated.\n\nFor BasicPlugins, this is used for both the plugin badges (see badges) and the template file (see source). For other Plugins, it is used only for badges, but you can always call it yourself as part of your hook implementation.\n\nBy default, an empty Dict is returned.\n\n\n\n\n\n","category":"function"},{"location":"developer/#","page":"Developer Guide","title":"Developer Guide","text":"Finally, we implement hook, which is the real workhorse for the plugin. Inside of this function, we generate a couple of files with the help of a few more text templating functions.","category":"page"},{"location":"developer/#","page":"Developer Guide","title":"Developer Guide","text":"render_file\nrender_text\ngen_file\ncombined_view\ntags","category":"page"},{"location":"developer/#PkgTemplates.render_file","page":"Developer Guide","title":"PkgTemplates.render_file","text":"render_file(file::AbstractString view::Dict{<:AbstractString}, tags) -> String\n\nRender 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.\n\n\n\n\n\n","category":"function"},{"location":"developer/#PkgTemplates.render_text","page":"Developer Guide","title":"PkgTemplates.render_text","text":"render_text(text::AbstractString, view::Dict{<:AbstractString}, tags=nothing) -> String\n\nRender 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.\n\n\n\n\n\n","category":"function"},{"location":"developer/#PkgTemplates.gen_file","page":"Developer Guide","title":"PkgTemplates.gen_file","text":"gen_file(file::AbstractString, text::AbstractString)\n\nCreate a new file containing some given text. Trailing whitespace is removed, and the file will end with a newline.\n\n\n\n\n\n","category":"function"},{"location":"developer/#PkgTemplates.combined_view","page":"Developer Guide","title":"PkgTemplates.combined_view","text":"combined_view(::Plugin, ::Template, pkg::AbstractString) -> Dict{String, Any}\n\nThis function combines view and user_view for use in text templating. If you're doing manual file creation or text templating (i.e. writing Plugins that are not BasicPlugins), then you should use this function rather than either of the former two.\n\nnote: Note\nDo not implement this function yourself! If you're implementing a plugin, you should implement view. If you're customizing a plugin as a user, you should implement user_view.\n\n\n\n\n\n","category":"function"},{"location":"developer/#PkgTemplates.tags","page":"Developer Guide","title":"PkgTemplates.tags","text":"tags(::Plugin) -> Tuple{String, String}\n\nReturn the delimiters used for text templating. See the Citation plugin for a rare case where changing the tags is necessary.\n\nBy default, the tags are \"{{\" and \"}}\".\n\n\n\n\n\n","category":"function"},{"location":"developer/#","page":"Developer Guide","title":"Developer Guide","text":"For more information on text templating, see the BasicPlugin Walkthrough and the section on Custom Template Files.","category":"page"},{"location":"developer/#Example:-Git-1","page":"Developer Guide","title":"Example: Git","text":"","category":"section"},{"location":"developer/#","page":"Developer Guide","title":"Developer Guide","text":"struct Git <: Plugin end\n\npriority(::Git, ::typeof(posthook)) = 5\n\nfunction validate(::Git, ::Template)\n foreach((\"user.name\", \"user.email\")) do k\n if isempty(LibGit2.getconfig(k, \"\"))\n throw(ArgumentError(\"Git: Global Git config is missing required value '$k'\"))\n end\n end\nend\n\nfunction prehook(::Git, t::Template, pkg_dir::AbstractString)\n LibGit2.with(LibGit2.init(pkg_dir)) do repo\n LibGit2.commit(repo, \"Initial commit\")\n pkg = basename(pkg_dir)\n url = \"https://$(t.host)/$(t.user)/$pkg.jl\"\n close(GitRemote(repo, \"origin\", url))\n end\nend\n\nfunction hook(::Git, t::Template, pkg_dir::AbstractString)\n ignore = mapreduce(gitignore, append!, t.plugins)\n unique!(sort!(ignore))\n gen_file(joinpath(pkg_dir, \".gitignore\"), join(ignore, \"\\n\"))\nend\n\nfunction posthook(::Git, ::Template, pkg_dir::AbstractString)\n LibGit2.with(GitRepo(pkg_dir)) do repo\n LibGit2.add!(repo, \".\")\n LibGit2.commit(repo, \"Files generated by PkgTemplates\")\n end\nend","category":"page"},{"location":"developer/#","page":"Developer Guide","title":"Developer Guide","text":"Validation and all three hooks are implemented:","category":"page"},{"location":"developer/#","page":"Developer Guide","title":"Developer Guide","text":"validate makes sure that all required Git configuration is present.\nprehook creates the Git repository for the package.\nhook generates the .gitignore file, using the special gitignore function.\nposthook adds and commits all the generated files.","category":"page"},{"location":"developer/#","page":"Developer Guide","title":"Developer Guide","text":"As previously mentioned, we use priority to make sure that we wait until all other plugins are finished their work before committing files.","category":"page"},{"location":"developer/#","page":"Developer Guide","title":"Developer Guide","text":"Hopefully, this demonstrates the level of control you have over the package generation process when developing plugins, and when it makes sense to exercise that power!","category":"page"},{"location":"developer/#BasicPlugin-Walkthrough-1","page":"Developer Guide","title":"BasicPlugin Walkthrough","text":"","category":"section"},{"location":"developer/#","page":"Developer Guide","title":"Developer Guide","text":"Most of the time, you don't really need all of the control that we showed off above. Plugins that subtype BasicPlugin perform a much more limited task. In general, they just generate one templated file.","category":"page"},{"location":"developer/#","page":"Developer Guide","title":"Developer Guide","text":"To illustrate, let's look at the Citation plugin, which creates a CITATION.bib file.","category":"page"},{"location":"developer/#","page":"Developer Guide","title":"Developer Guide","text":"@with_kw_noshow struct Citation <: BasicPlugin\n file::String = default_file(\"CITATION.bib\")\nend\n\nsource(p::Citation) = p.file\ndestination(::Citation) = \"CITATION.bib\"\n\ntags(::Citation) = \"<<\", \">>\"\n\nview(::Citation, t::Template, pkg::AbstractString) = Dict(\n \"AUTHORS\" => join(t.authors, \", \"),\n \"MONTH\" => month(today()),\n \"PKG\" => pkg,\n \"URL\" => \"https://$(t.host)/$(t.user)/$pkg.jl\",\n \"YEAR\" => year(today()),\n)","category":"page"},{"location":"developer/#","page":"Developer Guide","title":"Developer Guide","text":"Similar to the Documenter example above, we're defining a keyword constructor, and assigning a default template file from this repository. This plugin adds nothing to .gitignore, and it doesn't add any badges, so implementations for gitignore and badges are omitted.","category":"page"},{"location":"developer/#","page":"Developer Guide","title":"Developer Guide","text":"First, we implement source and destination to define where the template file comes from, and where it goes. These functions are specific to BasicPlugins, and have no effect on regular Plugins by default.","category":"page"},{"location":"developer/#","page":"Developer Guide","title":"Developer Guide","text":"source\ndestination","category":"page"},{"location":"developer/#PkgTemplates.source","page":"Developer Guide","title":"PkgTemplates.source","text":"source(::BasicPlugin) -> Union{String, Nothing}\n\nReturn the path to a plugin's template file, or nothing to indicate no file.\n\nBy default, nothing is returned.\n\n\n\n\n\n","category":"function"},{"location":"developer/#PkgTemplates.destination","page":"Developer Guide","title":"PkgTemplates.destination","text":"destination(::BasicPlugin) -> String\n\nReturn the destination, relative to the package root, of a plugin's configuration file.\n\nThis function must be implemented.\n\n\n\n\n\n","category":"function"},{"location":"developer/#","page":"Developer Guide","title":"Developer Guide","text":"Next, we implement tags. We briefly saw this function earlier, but in this case it's necessary to change its behaviour from the default. To see why, it might help to see the template file in its entirety:","category":"page"},{"location":"developer/#","page":"Developer Guide","title":"Developer Guide","text":"@misc{<<&PKG>>.jl,\n\tauthor = {<<&AUTHORS>>},\n\ttitle = {<<&PKG>>.jl},\n\turl = {<<&URL>>},\n\tversion = {v0.1.0},\n\tyear = {<<&YEAR>>},\n\tmonth = {<<&MONTH>>}\n}","category":"page"},{"location":"developer/#","page":"Developer Guide","title":"Developer Guide","text":"Because the file contains its own {} delimiters, we need to use different ones for templating to work properly.","category":"page"},{"location":"developer/#","page":"Developer Guide","title":"Developer Guide","text":"Finally, we implement view to fill in the placeholders that we saw in the template file.","category":"page"},{"location":"developer/#Doing-Extra-Work-With-BasicPlugins-1","page":"Developer Guide","title":"Doing Extra Work With BasicPlugins","text":"","category":"section"},{"location":"developer/#","page":"Developer Guide","title":"Developer Guide","text":"Notice that we didn't have to implement hook for our plugin. It's implemented for all BasicPlugins, like so:","category":"page"},{"location":"developer/#","page":"Developer Guide","title":"Developer Guide","text":"function render_plugin(p::BasicPlugin, t::Template, pkg::AbstractString)\n return render_file(source(p), combined_view(p, t, pkg), tags(p))\nend\n\nfunction hook(p::BasicPlugin, t::Template, pkg_dir::AbstractString)\n source(p) === nothing && return\n pkg = basename(pkg_dir)\n path = joinpath(pkg_dir, destination(p))\n text = render_plugin(p, t, pkg)\n gen_file(path, text)\nend","category":"page"},{"location":"developer/#","page":"Developer Guide","title":"Developer Guide","text":"But what if we want to do a little more than just generate one file?","category":"page"},{"location":"developer/#","page":"Developer Guide","title":"Developer Guide","text":"A good example of this is the Tests plugin. It creates runtests.jl, but it also modifies the Project.toml to include the Test dependency.","category":"page"},{"location":"developer/#","page":"Developer Guide","title":"Developer Guide","text":"Of course, we could use a normal Plugin, but it turns out there's a way to avoid that while still getting the extra capbilities that we want.","category":"page"},{"location":"developer/#","page":"Developer Guide","title":"Developer Guide","text":"The plugin implements its own hook, but uses invoke to avoid duplicating the file creation code:","category":"page"},{"location":"developer/#","page":"Developer Guide","title":"Developer Guide","text":"@with_kw_noshow struct Tests <: BasicPlugin\n file::String = default_file(\"runtests.jl\")\nend\n\nsource(p::Tests) = p.file\ndestination(::Tests) = joinpath(\"test\", \"runtests.jl\")\nview(::Tests, ::Template, pkg::AbstractString) = Dict(\"PKG\" => pkg)\n\nfunction hook(p::Tests, t::Template, pkg_dir::AbstractString)\n # Do the normal BasicPlugin behaviour to create the test script.\n invoke(hook, Tuple{BasicPlugin, Template, AbstractString}, p, t, pkg_dir)\n # Do some other work.\n add_test_dependency()\nend","category":"page"},{"location":"developer/#","page":"Developer Guide","title":"Developer Guide","text":"There is also a default validate implementation for BasicPlugins, which checks that the plugin's source file exists, and throws an ArgumentError otherwise. If you want to extend the validation but keep the file existence check, use the invoke method as described above.","category":"page"},{"location":"developer/#","page":"Developer Guide","title":"Developer Guide","text":"For more examples, see the plugins in the Continuous Integration (CI) and Code Coverage sections.","category":"page"},{"location":"developer/#Miscellaneous-Tips-1","page":"Developer Guide","title":"Miscellaneous Tips","text":"","category":"section"},{"location":"developer/#Writing-Template-Files-1","page":"Developer Guide","title":"Writing Template Files","text":"","category":"section"},{"location":"developer/#","page":"Developer Guide","title":"Developer Guide","text":"For an overview of writing template files for Mustache.jl, see Custom Template Files in the user guide.","category":"page"},{"location":"developer/#Predicates-1","page":"Developer Guide","title":"Predicates","text":"","category":"section"},{"location":"developer/#","page":"Developer Guide","title":"Developer Guide","text":"There are a few predicate functions for plugins that are occasionally used to answer questions like \"does this Template have any code coverage plugins?\". If you're implementing a plugin that fits into one of the following categories, it would be wise to implement the corresponding predicate function to return true for instances of your type.","category":"page"},{"location":"developer/#","page":"Developer Guide","title":"Developer Guide","text":"needs_username\nis_ci\nis_coverage","category":"page"},{"location":"developer/#PkgTemplates.needs_username","page":"Developer Guide","title":"PkgTemplates.needs_username","text":"needs_username(::Plugin) -> Bool\n\nDetermine 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, you should implement this function and return true.\n\n\n\n\n\n","category":"function"},{"location":"developer/#PkgTemplates.is_ci","page":"Developer Guide","title":"PkgTemplates.is_ci","text":"is_ci(::Plugin) -> Bool\n\nDetermine whether or not a plugin is a CI plugin. If you are adding a CI plugin, you should implement this function and return true.\n\n\n\n\n\n","category":"function"},{"location":"developer/#PkgTemplates.is_coverage","page":"Developer Guide","title":"PkgTemplates.is_coverage","text":"is_coverage(::Plugin) -> Bool\n\nDetermine whether or not a plugin is a coverage plugin. If you are adding a coverage plugin, you should implement this function and return true.\n\n\n\n\n\n","category":"function"},{"location":"developer/#Formatting-Version-Numbers-1","page":"Developer Guide","title":"Formatting Version Numbers","text":"","category":"section"},{"location":"developer/#","page":"Developer Guide","title":"Developer Guide","text":"When writing configuration files for CI services, working with version numbers is often needed. There are a few convenience functions that can be used to make this a little bit easier.","category":"page"},{"location":"developer/#","page":"Developer Guide","title":"Developer Guide","text":"compat_version\nformat_version\ncollect_versions","category":"page"},{"location":"developer/#PkgTemplates.compat_version","page":"Developer Guide","title":"PkgTemplates.compat_version","text":"compat_version(v::VersionNumber) -> String\n\nFormat a VersionNumber to exclude trailing zero components.\n\n\n\n\n\n","category":"function"},{"location":"developer/#PkgTemplates.format_version","page":"Developer Guide","title":"PkgTemplates.format_version","text":"format_version(v::Union{VersionNumber, AbstractString}) -> String\n\nStrip everything but the major and minor release from a VersionNumber. Strings are left in their original form.\n\n\n\n\n\n","category":"function"},{"location":"developer/#PkgTemplates.collect_versions","page":"Developer Guide","title":"PkgTemplates.collect_versions","text":"collect_versions(t::Template, versions::Vector) -> Vector{String}\n\nCombine t's Julia version with versions, and format them as major.minor. This is useful for creating lists of versions to be included in CI configurations.\n\n\n\n\n\n","category":"function"},{"location":"user/#","page":"User Guide","title":"User Guide","text":"CurrentModule = PkgTemplates","category":"page"},{"location":"user/#PkgTemplates-User-Guide-1","page":"User Guide","title":"PkgTemplates User Guide","text":"","category":"section"},{"location":"user/#","page":"User Guide","title":"User Guide","text":"Pages = [\"user.md\"]","category":"page"},{"location":"user/#","page":"User Guide","title":"User Guide","text":"Using PkgTemplates is straightforward. Just create a Template, and call it on a package name to generate that package:","category":"page"},{"location":"user/#","page":"User Guide","title":"User Guide","text":"using PkgTemplates\nt = Template()\nt(\"MyPkg\")","category":"page"},{"location":"user/#Template-1","page":"User Guide","title":"Template","text":"","category":"section"},{"location":"user/#","page":"User Guide","title":"User Guide","text":"Template","category":"page"},{"location":"user/#PkgTemplates.Template","page":"User Guide","title":"PkgTemplates.Template","text":"Template(; kwargs...)\n\nA configuration used to generate packages.\n\nKeyword Arguments\n\nUser Options\n\nuser::AbstractString=\"username\": GitHub (or other code hosting service) username. 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.\nauthors::Union{AbstractString, Vector{<:AbstractString}}=\"name <email>\": Package authors. Like user, it takes its default value from the global Git config (user.name and user.email).\n\nPackage Options\n\ndir::AbstractString=\"~/.julia/dev\": Directory to place packages in.\nhost::AbstractString=\"github.com\": URL to the code hosting service where packages will reside.\njulia::VersionNumber=v\"1.0.0\": Minimum allowed Julia version.\n\nTemplate Plugins\n\nplugins::Vector{<:Plugin}=Plugin[]: A list of Plugins used by the template.\ndisable_defaults::Vector{DataType}=DataType[]: Default plugins to disable. The default plugins are ProjectFile, SrcDir, Tests, Readme, License, and Git. To override a default plugin instead of disabling it altogether, supply it via plugins.\n\n\n\nTo create a package from a Template, use the following syntax:\n\njulia> t = Template();\n\njulia> t(\"PkgName\")\n\n\n\n\n\n","category":"type"},{"location":"user/#Plugins-1","page":"User Guide","title":"Plugins","text":"","category":"section"},{"location":"user/#","page":"User Guide","title":"User Guide","text":"Plugins add functionality to Templates. There are a number of plugins available to automate common boilerplate tasks.","category":"page"},{"location":"user/#Default-Plugins-1","page":"User Guide","title":"Default Plugins","text":"","category":"section"},{"location":"user/#","page":"User Guide","title":"User Guide","text":"These plugins are included by default. They can be overridden by supplying another value via the plugins keyword, or disabled by supplying the type via the disable_defaults keyword.","category":"page"},{"location":"user/#","page":"User Guide","title":"User Guide","text":"ProjectFile\nSrcDir\nTests\nReadme\nLicense\nGit\nTagBot","category":"page"},{"location":"user/#PkgTemplates.ProjectFile","page":"User Guide","title":"PkgTemplates.ProjectFile","text":"ProjectFile(; version=v\"0.1.0\")\n\nCreates a Project.toml.\n\nKeyword Arguments\n\nversion::VersionNumber: The initial version of created packages.\n\n\n\n\n\n","category":"type"},{"location":"user/#PkgTemplates.SrcDir","page":"User Guide","title":"PkgTemplates.SrcDir","text":"SrcDir(; file=\"~/build/invenia/PkgTemplates.jl/templates/src/module.jl\")\n\nCreates a module entrypoint.\n\nKeyword Arguments\n\nfile::AbstractString: Template file for src/<module>.jl.\n\n\n\n\n\n","category":"type"},{"location":"user/#PkgTemplates.Tests","page":"User Guide","title":"PkgTemplates.Tests","text":"Tests(; file=\"~/build/invenia/PkgTemplates.jl/templates/test/runtests.jl\", project=false)\n\nSets up testing for packages.\n\nKeyword Arguments\n\nfile::AbstractString: Template file for runtests.jl.\nproject::Bool: Whether or not to create a new project for tests (test/Project.toml). See here for more details.\n\nnote: Note\nManaging test dependencies with test/Project.toml is only supported in Julia 1.2 and later.\n\n\n\n\n\n","category":"type"},{"location":"user/#PkgTemplates.Readme","page":"User Guide","title":"PkgTemplates.Readme","text":"Readme(;\n file=\"~/build/invenia/PkgTemplates.jl/templates/README.md\",\n destination=\"README.md\",\n inline_badges=false,\n)\n\nCreates a README file that contains badges for other included plugins.\n\nKeyword Arguments\n\nfile::AbstractString: Template file for the README.\ndestination::AbstractString: File destination, relative to the repository root. For example, values of \"README\" or \"README.rst\" might be desired.\ninline_badges::Bool: Whether or not to put the badges on the same line as the package name.\n\n\n\n\n\n","category":"type"},{"location":"user/#PkgTemplates.License","page":"User Guide","title":"PkgTemplates.License","text":"License(; name=\"MIT\", path=nothing, destination=\"LICENSE\")\n\nCreates a license file.\n\nKeyword Arguments\n\nname::AbstractString: Name of a license supported by PkgTemplates. Available licenses can be seen here.\npath::Union{AbstractString, Nothing}: Path to a custom license file. This keyword takes priority over name.\ndestination::AbstractString: File destination, relative to the repository root. For example, \"LICENSE.md\" might be desired.\n\n\n\n\n\n","category":"type"},{"location":"user/#PkgTemplates.Git","page":"User Guide","title":"PkgTemplates.Git","text":"Git(; ignore=String[], ssh=false, manifest=false, gpgsign=false)\n\nCreates a Git repository and a .gitignore file.\n\nKeyword Arguments\n\nignore::Vector{<:AbstractString}: Patterns to add to the .gitignore. See also: gitignore.\nssh::Bool: Whether or not to use SSH for the remote. If left unset, HTTPS is used.\nmanifest::Bool: Whether or not to commit Manifest.toml.\ngpgsign::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.\n\n\n\n\n\n","category":"type"},{"location":"user/#PkgTemplates.TagBot","page":"User Guide","title":"PkgTemplates.TagBot","text":"TagBot(; destination=\"TagBot.yml\", registry=nothing, dispatch=false)\n\nAdds GitHub release support via TagBot.\n\nKeyword Arguments\n\ndestination::AbstractString: Destination of the workflow file, relative to .github/workflows.\nregistry::Union{AbstractString, Nothing}: Custom registry, in the format owner/repo.\ndispatch::Bool: Whether or not to enable the dispatch option.\n\n\n\n\n\n","category":"type"},{"location":"user/#Continuous-Integration-(CI)-1","page":"User Guide","title":"Continuous Integration (CI)","text":"","category":"section"},{"location":"user/#","page":"User Guide","title":"User Guide","text":"These plugins will create the configuration files of common CI services for you.","category":"page"},{"location":"user/#","page":"User Guide","title":"User Guide","text":"AppVeyor\nCirrusCI\nDroneCI\nGitHubActions\nGitLabCI\nTravisCI","category":"page"},{"location":"user/#PkgTemplates.AppVeyor","page":"User Guide","title":"PkgTemplates.AppVeyor","text":"AppVeyor(;\n file=\"~/build/invenia/PkgTemplates.jl/templates/appveyor.yml\",\n x86=false,\n coverage=true,\n extra_versions=[\"1.0\", \"1.3\", \"nightly\"],\n)\n\nIntegrates your packages with AppVeyor via AppVeyor.jl.\n\nKeyword Arguments\n\nfile::AbstractString: Template file for .appveyor.yml.\nx86::Bool: Whether or not to run builds on 32-bit systems, in addition to the default 64-bit builds.\ncoverage::Bool: Whether or not to publish code coverage. Codecov must also be included.\nextra_versions::Vector: Extra Julia versions to test, as strings or VersionNumbers.\n\n\n\n\n\n","category":"type"},{"location":"user/#PkgTemplates.CirrusCI","page":"User Guide","title":"PkgTemplates.CirrusCI","text":"CirrusCI(;\n file=\"~/build/invenia/PkgTemplates.jl/templates/cirrus.yml\",\n image=\"freebsd-12-0-release-amd64\",\n coverage=true,\n extra_versions=[\"1.0\", \"1.3\", \"nightly\"],\n)\n\nIntegrates your packages with Cirrus CI via CirrusCI.jl.\n\nKeyword Arguments\n\nfile::AbstractString: Template file for .cirrus.yml.\nimage::AbstractString: The FreeBSD image to be used.\ncoverage::Bool: Whether or not to publish code coverage. Codecov must also be included.\nextra_versions::Vector: Extra Julia versions to test, as strings or VersionNumbers.\n\nnote: Note\nCode coverage submission from Cirrus CI is not yet supported by Coverage.jl.\n\n\n\n\n\n","category":"type"},{"location":"user/#PkgTemplates.DroneCI","page":"User Guide","title":"PkgTemplates.DroneCI","text":"DroneCI(;\n file=\"~/build/invenia/PkgTemplates.jl/templates/drone.star\",\n amd64=true,\n arm=false,\n arm64=false,\n extra_versions=[\"1.0\", \"1.3\"],\n)\n\nIntegrates your packages with Drone CI.\n\nKeyword Arguments\n\nfile::AbstractString: Template file for .drone.star.\ndestination::AbstractString: File destination, relative to the repository root. For example, you might want to generate a .drone.yml instead of the default Starlark file.\namd64::Bool: Whether or not to run builds on AMD64.\narm::Bool: Whether or not to run builds on ARM (32-bit).\narm64::Bool: Whether or not to run builds on ARM64.\nextra_versions::Vector: Extra Julia versions to test, as strings or VersionNumbers.\n\nnote: Note\nNightly Julia is not supported.\n\n\n\n\n\n","category":"type"},{"location":"user/#PkgTemplates.GitHubActions","page":"User Guide","title":"PkgTemplates.GitHubActions","text":"GitHubActions(;\n file=\"~/build/invenia/PkgTemplates.jl/templates/github/workflows/ci.yml\",\n destination=\"ci.yml\",\n linux=true,\n osx=true,\n windows=true,\n x64=true,\n x86=false,\n coverage=true,\n extra_versions=[\"1.0\", \"1.3\", \"nightly\"],\n)\n\nIntegrates your packages with GitHub Actions.\n\nKeyword Arguments\n\nfile::AbstractString: Template file for the workflow file.\ndestination::AbstractString: Destination of the workflow file, relative to .github/workflows.\nlinux::Bool: Whether or not to run builds on Linux.\nosx::Bool: Whether or not to run builds on OSX (MacOS).\nwindows::Bool: Whether or not to run builds on Windows.\nx64::Bool: Whether or not to run builds on 64-bit architecture.\nx86::Bool: Whether or not to run builds on 32-bit architecture.\ncoverage::Bool: Whether or not to publish code coverage. Another code coverage plugin such as Codecov must also be included.\nextra_versions::Vector: Extra Julia versions to test, as strings or VersionNumbers.\n\nnote: Note\nIf using coverage plugins, don't forget to manually add your API tokens as secrets, as described here.\n\n\n\n\n\n","category":"type"},{"location":"user/#PkgTemplates.GitLabCI","page":"User Guide","title":"PkgTemplates.GitLabCI","text":"GitLabCI(;\n file=\"~/build/invenia/PkgTemplates.jl/templates/gitlab-ci.yml\",\n coverage=true,\n extra_versions=[\"1.0\", \"1.3\"],\n)\n\nIntegrates your packages with GitLab CI.\n\nKeyword Arguments\n\nfile::AbstractString: Template file for .gitlab-ci.yml.\ncoverage::Bool: Whether or not to compute code coverage.\nextra_versions::Vector: Extra Julia versions to test, as strings or VersionNumbers.\n\nGitLab Pages\n\nDocumentation can be generated by including a Documenter{GitLabCI} plugin. See Documenter for more information.\n\nnote: Note\nNightly Julia is not supported.\n\n\n\n\n\n","category":"type"},{"location":"user/#PkgTemplates.TravisCI","page":"User Guide","title":"PkgTemplates.TravisCI","text":"TravisCI(;\n file=\"~/build/invenia/PkgTemplates.jl/templates/travis.yml\",\n linux=true,\n osx=true,\n windows=true,\n x64=true,\n x86=false,\n arm64=false,\n coverage=true,\n extra_versions=[\"1.0\", \"1.3\", \"nightly\"],\n)\n\nIntegrates your packages with Travis CI.\n\nKeyword Arguments\n\nfile::AbstractString: Template file for .travis.yml.\nlinux::Bool: Whether or not to run builds on Linux.\nosx::Bool: Whether or not to run builds on OSX (MacOS).\nwindows::Bool: Whether or not to run builds on Windows.\nx64::Bool: Whether or not to run builds on 64-bit architecture.\nx86::Bool: Whether or not to run builds on 32-bit architecture.\narm64::Bool: Whether or not to run builds on the ARM64 architecture.\ncoverage::Bool: Whether or not to publish code coverage. Another code coverage plugin such as Codecov must also be included.\nextra_versions::Vector: Extra Julia versions to test, as strings or VersionNumbers.\n\n\n\n\n\n","category":"type"},{"location":"user/#Code-Coverage-1","page":"User Guide","title":"Code Coverage","text":"","category":"section"},{"location":"user/#","page":"User Guide","title":"User Guide","text":"These plugins will enable code coverage reporting from CI.","category":"page"},{"location":"user/#","page":"User Guide","title":"User Guide","text":"Codecov\nCoveralls","category":"page"},{"location":"user/#PkgTemplates.Codecov","page":"User Guide","title":"PkgTemplates.Codecov","text":"Codecov(; file=nothing)\n\nSets up code coverage submission from CI to Codecov.\n\nKeyword Arguments\n\nfile::Union{AbstractString, Nothing}: Template file for .codecov.yml, or nothing to create no file.\n\n\n\n\n\n","category":"type"},{"location":"user/#PkgTemplates.Coveralls","page":"User Guide","title":"PkgTemplates.Coveralls","text":"Coveralls(; file=nothing)\n\nSets up code coverage submission from CI to Coveralls.\n\nKeyword Arguments\n\nfile::Union{AbstractString, Nothing}: Template file for .coveralls.yml, or nothing to create no file.\n\n\n\n\n\n","category":"type"},{"location":"user/#Documentation-1","page":"User Guide","title":"Documentation","text":"","category":"section"},{"location":"user/#","page":"User Guide","title":"User Guide","text":"Documenter","category":"page"},{"location":"user/#PkgTemplates.Documenter","page":"User Guide","title":"PkgTemplates.Documenter","text":"Documenter{T<:Union{TravisCI, GitLabCI, Nothing}}(;\n make_jl=\"~/build/invenia/PkgTemplates.jl/templates/docs/make.jl\",\n index_md=\"~/build/invenia/PkgTemplates.jl/templates/docs/src/index.md\",\n assets=String[],\n canonical_url=make_canonical(T),\n makedocs_kwargs=Dict{Symbol, Any}(),\n)\n\nSets up documentation generation via Documenter.jl. Documentation deployment depends on T, where T is some supported CI plugin, or Nothing to only support local documentation builds.\n\nSupported Type Parameters\n\nGitHubActions: Deploys documentation to GitHub Pages with the help of GitHubActions.\nTravisCI: Deploys documentation to GitHub Pages with the help of TravisCI.\nGitLabCI: Deploys documentation to GitLab Pages with the help of GitLabCI.\nNothing (default): Does not set up documentation deployment.\n\nKeyword Arguments\n\nmake_jl::AbstractString: Template file for make.jl.\nindex_md::AbstractString: Template file for index.md.\nassets::Vector{<:AbstractString}: Extra assets for the generated site.\ncanonical_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 and GitLabCI, respectively. If set to nothing, no canonical URL is set.\nmakedocs_kwargs::Dict{Symbol}: Extra keyword arguments to be inserted into makedocs.\n\nnote: Note\nIf deploying documentation with Travis CI, don't forget to complete the required configuration.\n\n\n\n\n\n","category":"type"},{"location":"user/#Miscellaneous-1","page":"User Guide","title":"Miscellaneous","text":"","category":"section"},{"location":"user/#","page":"User Guide","title":"User Guide","text":"Develop\nCompatHelper\nCitation","category":"page"},{"location":"user/#PkgTemplates.Develop","page":"User Guide","title":"PkgTemplates.Develop","text":"Develop()\n\nAdds generated packages to the current environment by deving them. See the Pkg documentation here for more details.\n\n\n\n\n\n","category":"type"},{"location":"user/#PkgTemplates.CompatHelper","page":"User Guide","title":"PkgTemplates.CompatHelper","text":"CompatHelper(;\n file=\"~/build/invenia/PkgTemplates.jl/templates/github/workflows/CompatHelper.yml\",\n destination=\"CompatHelper.yml\",\n)\n\nIntegrates your packages with CompatHelper via GitHub Actions.\n\nKeyword Arguments\n\nfile::AbstractString: Template file for the workflow file.\ndestination::AbstractString: Destination of the workflow file, relative to .github/workflows.\n\n\n\n\n\n","category":"type"},{"location":"user/#PkgTemplates.Citation","page":"User Guide","title":"PkgTemplates.Citation","text":"Citation(; file=\"~/build/invenia/PkgTemplates.jl/templates/CITATION.bib\", readme=false)\n\nCreates a CITATION.bib file for citing package repositories.\n\nKeyword Arguments\n\nfile::AbstractString: Template file for CITATION.bib.\nreadme::Bool: Whether or not to include a section about citing in the README.\n\n\n\n\n\n","category":"type"},{"location":"user/#A-More-Complicated-Example-1","page":"User Guide","title":"A More Complicated Example","text":"","category":"section"},{"location":"user/#","page":"User Guide","title":"User Guide","text":"Here are a few example templates that use the options and plugins explained above.","category":"page"},{"location":"user/#","page":"User Guide","title":"User Guide","text":"This one includes plugins suitable for a project hosted on GitHub, and some other customizations:","category":"page"},{"location":"user/#","page":"User Guide","title":"User Guide","text":"Template(; \n user=\"my-username\",\n dir=\"~/code\",\n authors=\"Acme Corp\",\n julia=v\"1.1\",\n plugins=[\n License(; name=\"MPL\"),\n Git(; manifest=true, ssh=true),\n GitHubActions(; x86=true),\n Codecov(),\n Documenter{GitHubActions}(),\n Develop(),\n ],\n)","category":"page"},{"location":"user/#","page":"User Guide","title":"User Guide","text":"Here's one that works well for projects hosted on GitLab:","category":"page"},{"location":"user/#","page":"User Guide","title":"User Guide","text":"Template(;\n user=\"my-username\",\n host=\"gitlab.com\",\n plugins=[\n GitLabCI(),\n Documenter{GitLabCI}(),\n ],\n)","category":"page"},{"location":"user/#Custom-Template-Files-1","page":"User Guide","title":"Custom Template Files","text":"","category":"section"},{"location":"user/#","page":"User Guide","title":"User Guide","text":"note: Templates vs Templating\nThis documentation refers plenty to Templates, the package's main type, but it also refers to \"template files\" and \"text templating\", which are plaintext files with placeholders to be filled with data, and the technique of filling those placeholders with data, respectively.These concepts should be familiar if you've used Jinja or Mustache (Mustache is the particular flavour used by PkgTemplates, via Mustache.jl). Please keep the difference between these two things in mind!","category":"page"},{"location":"user/#","page":"User Guide","title":"User Guide","text":"Many plugins support a file argument or similar, which sets the path to the template file to be used for generating files. Each plugin has a sensible default that should make sense for most people, but you might have a specialized workflow that requires a totally different template file.","category":"page"},{"location":"user/#","page":"User Guide","title":"User Guide","text":"If that's the case, a basic understanding of Mustache's syntax is required. Here's an example template file:","category":"page"},{"location":"user/#","page":"User Guide","title":"User Guide","text":"Hello, {{{name}}}.\n\n{{#weather}}\nIt's {{{weather}}} outside. \n{{/weather}}\n{{^weather}}\nI don't know what the weather outside is.\n{{/weather}}\n\n{{#has_things}}\nI have the following things:\n{{/has_things}}\n{{#things}}\n- Here's a thing: {{{.}}}\n{{/things}}\n\n{{#people}}\n- {{{name}}} is {{{mood}}}\n{{/people}}","category":"page"},{"location":"user/#","page":"User Guide","title":"User Guide","text":"In the first section, name is a key, and its value replaces {{{name}}}.","category":"page"},{"location":"user/#","page":"User Guide","title":"User Guide","text":"In the second section, weather's value may or may not exist. If it does exist, then \"It's weather outside\" is printed. Otherwise, \"I don't know what the weather outside is\" is printed. Mustache uses a notion of \"truthiness\" similar to Python or JavaScript, where values of nothing, false, or empty collections are all considered to not exist.","category":"page"},{"location":"user/#","page":"User Guide","title":"User Guide","text":"In the third section, has_things' value is printed if it's truthy. Then, if the things list is truthy (i.e. not empty), its values are each printed on their own line. The reason that we have two separate keys is that {{#things}} iterates over the whole things list, even when there are no {{{.}}} placeholders, which would duplicate \"I have the following things:\" n times.","category":"page"},{"location":"user/#","page":"User Guide","title":"User Guide","text":"The fourth section iterates over the people list, but instead of using the {{{.}}} placeholder, we have name and mood, which are keys or fields of the list elements. Most types are supported here, including Dicts and structs. NamedTuples require you to use {{{:name}}} instead of the normal {{{name}}}, though.","category":"page"},{"location":"user/#","page":"User Guide","title":"User Guide","text":"You might notice that some curlies are in groups of two ({{key}}), and some are in groups of three ({{{key}}}). Whenever we want to subtitute in a value, using the triple curlies disables HTML escaping, which we rarely want for the types of files we're creating. If you do want escaping, just use the double curlies. And if you're using different delimiters, for example <<foo>>, use <<&foo>> to disable escaping.","category":"page"},{"location":"user/#","page":"User Guide","title":"User Guide","text":"Assuming the following view:","category":"page"},{"location":"user/#","page":"User Guide","title":"User Guide","text":"struct Person; name::String; mood::String; end\nthings = [\"a\", \"b\", \"c\"]\nview = Dict(\n \"name\" => \"Chris\",\n \"weather\" => \"sunny\",\n \"has_things\" => !isempty(things),\n \"things\" => things,\n \"people\" => [Person(\"John\", \"happy\"), Person(\"Jane\", \"sad\")],\n)","category":"page"},{"location":"user/#","page":"User Guide","title":"User Guide","text":"Our example template would produce this:","category":"page"},{"location":"user/#","page":"User Guide","title":"User Guide","text":"Hello, Chris.\n\nIt's sunny outside.\n\nI have the following things:\n- Here's a thing: a\n- Here's a thing: b\n- Here's a thing: c\n\n- John is happy\n- Jane is sad","category":"page"},{"location":"user/#Extending-Existing-Plugins-1","page":"User Guide","title":"Extending Existing Plugins","text":"","category":"section"},{"location":"user/#","page":"User Guide","title":"User Guide","text":"Most of the existing plugins generate a file from a template file. If you want to use custom template files, you may run into situations where the data passed into the templating engine is not sufficient. In this case, you can look into implementing user_view to supply whatever data is necessary for your use case.","category":"page"},{"location":"user/#","page":"User Guide","title":"User Guide","text":"user_view","category":"page"},{"location":"user/#PkgTemplates.user_view","page":"User Guide","title":"PkgTemplates.user_view","text":"user_view(::Plugin, ::Template, pkg::AbstractString) -> Dict{String, Any}\n\nThe same as view, but for use by package users for extension.\n\nValues returned by this function will override those from view when the keys are the same.\n\n\n\n\n\n","category":"function"},{"location":"user/#","page":"User Guide","title":"User Guide","text":"For example, suppose you were using the Readme plugin with a custom template file that looked like this:","category":"page"},{"location":"user/#","page":"User Guide","title":"User Guide","text":"# {{PKG}}\n\nCreated on *{{TODAY}}*.","category":"page"},{"location":"user/#","page":"User Guide","title":"User Guide","text":"The view function supplies a value for PKG, but it does not supply a value for TODAY. Rather than override view, we can implement this function to get both the default values and whatever else we need to add.","category":"page"},{"location":"user/#","page":"User Guide","title":"User Guide","text":"user_view(::Readme, ::Template, ::AbstractString) = Dict(\"TODAY\" => today())","category":"page"},{"location":"user/#Saving-Templates-1","page":"User Guide","title":"Saving Templates","text":"","category":"section"},{"location":"user/#","page":"User Guide","title":"User Guide","text":"One of the main reasons for PkgTemplates' existence is for new packages to be consistent. This means using the same template more than once, so we want a way to save a template to be used later.","category":"page"},{"location":"user/#","page":"User Guide","title":"User Guide","text":"Here's my recommendation for loading a template whenever it's needed:","category":"page"},{"location":"user/#","page":"User Guide","title":"User Guide","text":"function template()\n @eval using PkgTemplates\n Template(; #= ... =#)\nend","category":"page"},{"location":"user/#","page":"User Guide","title":"User Guide","text":"Add this to your startup.jl, and you can create your template from anywhere, without incurring any startup cost.","category":"page"},{"location":"user/#","page":"User Guide","title":"User Guide","text":"Another strategy is to write the string representation of the template to a Julia file:","category":"page"},{"location":"user/#","page":"User Guide","title":"User Guide","text":"const t = Template(; #= ... =#)\nopen(\"template.jl\", \"w\") do io\n println(io, \"using PkgTemplates\")\n sprint(show, io, t)\nend","category":"page"},{"location":"user/#","page":"User Guide","title":"User Guide","text":"Then the template is just an include away:","category":"page"},{"location":"user/#","page":"User Guide","title":"User Guide","text":"const t = include(\"template.jl\")","category":"page"},{"location":"user/#","page":"User Guide","title":"User Guide","text":"The only disadvantage to this approach is that the saved template is much less human-readable than code you wrote yourself.","category":"page"},{"location":"user/#","page":"User Guide","title":"User Guide","text":"One more method of saving templates is to simply use the Serialization package in the standard library:","category":"page"},{"location":"user/#","page":"User Guide","title":"User Guide","text":"const t = Template(; #= ... =#)\nusing Serialization\nopen(io -> serialize(io, t), \"template.bin\", \"w\")","category":"page"},{"location":"user/#","page":"User Guide","title":"User Guide","text":"Then simply deserialize to load:","category":"page"},{"location":"user/#","page":"User Guide","title":"User Guide","text":"using Serialization\nconst t = open(deserialize, \"template.bin\")","category":"page"},{"location":"user/#","page":"User Guide","title":"User Guide","text":"This approach has the same disadvantage as the previous one, and the serialization format is not guaranteed to be stable across Julia versions.","category":"page"},{"location":"migrating/#","page":"Migrating To PkgTemplates 0.7+","title":"Migrating To PkgTemplates 0.7+","text":"CurrentModule = PkgTemplates","category":"page"},{"location":"migrating/#Migrating-To-PkgTemplates-0.7-1","page":"Migrating To PkgTemplates 0.7+","title":"Migrating To PkgTemplates 0.7+","text":"","category":"section"},{"location":"migrating/#","page":"Migrating To PkgTemplates 0.7+","title":"Migrating To PkgTemplates 0.7+","text":"PkgTemplates 0.7 is a ground-up rewrite of the package with similar functionality but with updated APIs and internals. Here is a summary of things that existed in older versions but have been moved elsewhere or removed. However, it might be easier to just read the User Guide.","category":"page"},{"location":"migrating/#Template-keywords-1","page":"Migrating To PkgTemplates 0.7+","title":"Template keywords","text":"","category":"section"},{"location":"migrating/#","page":"Migrating To PkgTemplates 0.7+","title":"Migrating To PkgTemplates 0.7+","text":"The recurring theme is \"everything is a plugin now\".","category":"page"},{"location":"migrating/#","page":"Migrating To PkgTemplates 0.7+","title":"Migrating To PkgTemplates 0.7+","text":"Old New\nlicense=\"ISC\" plugins=[License(; name=\"ISC\")]\ndevelop=true * plugins=[Develop()]\ngit=false disable_defaults=[Git]\njulia_version=v\"1\" julia=v\"1\"\nssh=true plugins=[Git(; ssh=true)]\nmanifest=true plugins=[Git(; manifest=true)]","category":"page"},{"location":"migrating/#","page":"Migrating To PkgTemplates 0.7+","title":"Migrating To PkgTemplates 0.7+","text":"* develop=true was the default setting, but it is no longer the default in PkgTemplates 0.7+.","category":"page"},{"location":"migrating/#Plugins-1","page":"Migrating To PkgTemplates 0.7+","title":"Plugins","text":"","category":"section"},{"location":"migrating/#","page":"Migrating To PkgTemplates 0.7+","title":"Migrating To PkgTemplates 0.7+","text":"Aside from renamings, basically every plugin has had their constructors reworked. So if you are using anything non-default, you should consult the new docstring.","category":"page"},{"location":"migrating/#","page":"Migrating To PkgTemplates 0.7+","title":"Migrating To PkgTemplates 0.7+","text":"Old New\nGitHubPages Documenter{TravisCI}\nGitLabPages Documenter{GitLabCI}","category":"page"},{"location":"migrating/#Package-Generation-1","page":"Migrating To PkgTemplates 0.7+","title":"Package Generation","text":"","category":"section"},{"location":"migrating/#","page":"Migrating To PkgTemplates 0.7+","title":"Migrating To PkgTemplates 0.7+","text":"One less name to remember!","category":"page"},{"location":"migrating/#","page":"Migrating To PkgTemplates 0.7+","title":"Migrating To PkgTemplates 0.7+","text":"Old New\ngenerate(::Template, pkg::AbstractString) (::Template)(pkg::AbstractString)","category":"page"},{"location":"migrating/#Interactive-Templates-1","page":"Migrating To PkgTemplates 0.7+","title":"Interactive Templates","text":"","category":"section"},{"location":"migrating/#","page":"Migrating To PkgTemplates 0.7+","title":"Migrating To PkgTemplates 0.7+","text":"Currently not implemented, but will be in the future.","category":"page"},{"location":"migrating/#Other-Functions-1","page":"Migrating To PkgTemplates 0.7+","title":"Other Functions","text":"","category":"section"},{"location":"migrating/#","page":"Migrating To PkgTemplates 0.7+","title":"Migrating To PkgTemplates 0.7+","text":"Two less names to remember! Although it's unlikely that anyone used these.","category":"page"},{"location":"migrating/#","page":"Migrating To PkgTemplates 0.7+","title":"Migrating To PkgTemplates 0.7+","text":"Old New\navailable_licenses View licenses on GitHub\nshow_license View licenses on GitHub","category":"page"},{"location":"migrating/#Custom-Plugins-1","page":"Migrating To PkgTemplates 0.7+","title":"Custom Plugins","text":"","category":"section"},{"location":"migrating/#","page":"Migrating To PkgTemplates 0.7+","title":"Migrating To PkgTemplates 0.7+","text":"In addition to the changes in usage, custom plugins from older versions of PkgTemplates will not work in 0.7+. See the Developer Guide for more information on the new extension API.","category":"page"},{"location":"#","page":"Home","title":"Home","text":"CurrentModule = PkgTemplates","category":"page"},{"location":"#PkgTemplates-1","page":"Home","title":"PkgTemplates","text":"","category":"section"},{"location":"#","page":"Home","title":"Home","text":"PkgTemplates creates new Julia packages in an easy, repeatable, and customizable way.","category":"page"},{"location":"#Documentation-1","page":"Home","title":"Documentation","text":"","category":"section"},{"location":"#","page":"Home","title":"Home","text":"If you're looking to create new packages, see the User Guide.","category":"page"},{"location":"#","page":"Home","title":"Home","text":"If you want to create new plugins, see the Developer Guide.","category":"page"},{"location":"#","page":"Home","title":"Home","text":"if you're trying to migrate from an older version of PkgTemplates, see Migrating To PkgTemplates 0.7+.","category":"page"},{"location":"#Index-1","page":"Home","title":"Index","text":"","category":"section"},{"location":"#","page":"Home","title":"Home","text":"","category":"page"}]
|
|
}
|