diff options
author | Patrick Spek <p.spek@tyil.nl> | 2020-02-05 19:44:41 +0100 |
---|---|---|
committer | Patrick Spek <p.spek@tyil.nl> | 2020-02-05 19:44:41 +0100 |
commit | 1cd323319d417acd8cfd22096123fae9aa83945a (patch) | |
tree | f4bf3f0c34dc2c23e111e77403de2e29c86610e8 | |
parent | d5d12cc4a265fe0f1c4c92fd3da0f5ad7f0e882c (diff) | |
download | Dist::Maker-1cd323319d417acd8cfd22096123fae9aa83945a.tar.gz Dist::Maker-1cd323319d417acd8cfd22096123fae9aa83945a.tar.bz2 |
Add Pod6 docs
-rw-r--r-- | .gitlab-ci.yml | 23 | ||||
-rw-r--r-- | .travis.yml | 13 | ||||
-rw-r--r-- | META6.json | 1 | ||||
-rw-r--r-- | README.pod6 | 27 | ||||
-rw-r--r-- | lib/Dist/Maker.rakumod | 27 | ||||
-rw-r--r-- | lib/Dist/Maker/Config.rakumod | 101 |
6 files changed, 153 insertions, 39 deletions
diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml deleted file mode 100644 index ac43fbf..0000000 --- a/.gitlab-ci.yml +++ /dev/null @@ -1,23 +0,0 @@ -Dist::Manager: - only: - - master - image: rakudo-star - before_script: - - zef install . --deps-only --test-depends --/test - script: AUTHOR_TESTING=1 prove -v -e "perl6 -Ilib" t - artifacts: - name: "perl6-Dist-Manager" - paths: - - META6.json - - bin - - lib - - resources - - t - -test: - except: - - master - image: rakudo-star - before_script: - - zef install . --deps-only --test-depends --/test - script: AUTHOR_TESTING=1 prove -v -e "perl6 -Ilib" t diff --git a/.travis.yml b/.travis.yml deleted file mode 100644 index 077ddb0..0000000 --- a/.travis.yml +++ /dev/null @@ -1,13 +0,0 @@ -language: perl6 - -perl6: - - latest - -os: - - linux - -install: - - rakudobrew build zef - - zef install --deps-only . - -script: AUTHOR_TESTING=1 prove -v -e "perl6 -Ilib" t/ @@ -20,6 +20,7 @@ "Dist::Maker::Commands::Add": "lib/Dist/Maker/Commands/Add.rakumod", "Dist::Maker::Commands::Depend": "lib/Dist/Maker/Commands/Depend.rakumod", "Dist::Maker::Commands::New": "lib/Dist/Maker/Commands/New.rakumod", + "Dist::Maker::Config": "lib/Dist/Maker/Config.rakumod", "Dist::Maker::Exception": "lib/Dist/Maker/Exception.rakumod", "Dist::Maker::Util": "lib/Dist/Maker/Util.rakumod", "X::Dist::Maker::Clobber": "lib/X/Dist/Maker/Clobber.rakumod", diff --git a/README.pod6 b/README.pod6 index 9851df3..c9c8ca6 100644 --- a/README.pod6 +++ b/README.pod6 @@ -1,21 +1,42 @@ =begin pod -=NAME Dist::Manager +=NAME Dist::Maker =AUTHOR Patrick Spek <p.spek@tyil.work> =VERSION 0.0.0 =head1 Description -Manage Raku module distributions +Easily develop Raku modules. + +This is the successor to +L<C<App::Assixt>|https://home.tyil.nl/git/raku/App::Assixt/about/> =head1 Installation Install this module through L<zef|https://github.com/ugexe/zef>: =begin code :lang<sh> -zef install Dist::Manager +zef install Dist::Maker =end code +=head1 Documentation + +Documentation is written as L<Pod6|https://docs.raku.org/language/pod> +documents, and can be read with C<raku>'s C<--doc> option. + +=begin input +raku --doc Dist::Maker +=end input + +At your option, you can also use prettier readers, such as +L<C<p6doc>|https://modules.raku.org/search/?q=p6doc> or +L<C<App::Rakuman>|https://modules.raku.org/dist/App::Rakuman:cpan:TYIL>. + +=begin input +p6doc Dist::Maker +rakuman Dist::Maker +=end input + =head1 License This module is distributed under the terms of the AGPL-3.0. diff --git a/lib/Dist/Maker.rakumod b/lib/Dist/Maker.rakumod index b917f48..1f3e34d 100644 --- a/lib/Dist/Maker.rakumod +++ b/lib/Dist/Maker.rakumod @@ -49,12 +49,39 @@ multi sub dm-config ( =head1 Synopsis +=item1 rdm add <provide> [--kind=<Str>] +=item1 rdm depend <module> +=item1 rdm new + =head1 Description +C<Dist::Maker> is a utility for Raku module developers to make their life +easier. It is the successor to +L<C<App::Assixt>|https://home.tyil.nl/git/raku/App::Assixt/about/>. + +The bin utility is an acronym for I<B<R>aku B<D>ist B<M>aker>. + =head1 Examples +=head2 Creating a new module + +=begin input +rdm new My::New::Module +=end input + +=head2 Adding a new unit to your module + +=begin input +rdm add My::New::Grammar --kind=grammar +=end input + +The C<--kind> option will require some configuration. You should consult +C<Dist::Maker::Config>, I<Provide kinds> for more information. + =head1 See also +=item1 C<Dist::Maker::Config> + =end pod # vim: ft=perl6 noet diff --git a/lib/Dist/Maker/Config.rakumod b/lib/Dist/Maker/Config.rakumod new file mode 100644 index 0000000..2359459 --- /dev/null +++ b/lib/Dist/Maker/Config.rakumod @@ -0,0 +1,101 @@ +#! /usr/bin/env false + +=begin pod + +=NAME Dist::Maker::Config +=AUTHOR Patrick Spek <p.spek@tyil.work> +=VERSION 0.0.0 + +=head1 Configuration file location + + $XDG_CONFIG_HOME/rdm/config.toml + +The value of C<$XDG_CONFIG_HOME> will default to C<$HOME/.config> if it is not +set in your shell. + +=head2 Options + +The configuration of C<Dist::Maker> is split up in a number of sections. One +for each command, plus a I<main> for general configuration. + +=head3 main + +=defn quiet (= False) +When set to C<True>, output of C<Dist::Maker> commands will be reduced. + +=head3 depend + +=defn zef-install (= False) +When set to C<True>, any time you use the C<depend> command, it will also +attempt to run C<zef install> for that particular module. This may be +convenient to ensure the module you want to use is actually available on your +system, but calling C<zef> may be quite slow. + +=head3 new + +=defn path (= $HOME) +The default path to create new modules in. This does B<not> expand shell +variables! + +=head2 Templates + +C<Dist::Manager> can make use of templates when creating new files. These must +be placed in C<$XDG_CONFIG_HOME/rdm/templates>. The templates will be rendered +using L<Mustache|https://mustache.github.io/>. + +For examples of templates, please refer to L<tyil's +dotfiles|https://home.tyil.nl/git/dotfiles/tree/.config/rdm>. + +=head3 readme.rakudoc + +If the C<readme.rakudoc> template file exists, it will be used as the template +for a C<README.rakudoc> in the root directory of a new module. All the +variables found in the C<META6.json> of a module are available to use. + +=head3 provide.raku + +If the C<provide.raku> template file exists, it will be used as the basis for +every new provide file created using C<rdm add>. The following variables are +exposed to it. + +=defn meta +This contains all the information from the modules C<META6.json> I<before> the +new provide file is added. + +=defn this +This variable contains information on the current object being added. +Currently, this only comes with the C<provide> field, which holds the name of +the new provide unit. + +=defn body +This contains a simple string, C<# TODO>, unless you've specified a C<--kind> +that exists. For more information regarding the use of kinds, check the +I<Provide kinds> section. + +=head4 Provide kinds + +Provide kinds allow for a great level of customization, at the cost of +requiring more setup from the user. In the C<templates> directory inside the +main configuration directory, you can create a directory named C<kinds>. In +here, you can create files with the C<.raku> extension to use them as a I<kind> +of provide template. + +For instance, if you have a default layout for your grammars, and would like to +make it easier to create new grammars, create a C<grammar.raku> in the C<kinds> +directory. To use this layout, pass C<--kind=grammar> to the C<add> command. + +Provide kinds are also rendered using Mustache, and can access the following +variables. + +=defn meta +This contains all the information from the modules C<META6.json> I<before> the +new provide file is added. + +=defn this +This variable contains information on the current object being added. +Currently, this only comes with the C<provide> field, which holds the name of +the new provide unit. + +=end pod + +# vim: ft=raku noet sw=8 ts=8 |