Copyright 2021 <mario#include-once:org>

EXCLUSION: This project and its source code shall not be shared or hosted
=========  on GitHub. There's a sufficient amount of open source eggs in
           one proprietary basket. (Bitbucket or GitLab are fine).

Otherwise the MIT license applies:
              ===========

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to
deal in the Software without restriction, including without limitation the
rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
sell copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in
all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
IN THE SOFTWARE.

0.1.0 (unreleased)
 * ...

0.0.7 (2021-03-20)
 * Search and categories implemented.
 * Minimal settings window.
 * More menu options.
 * README, manpages.

0.0.5 (2021-03-19)
 * Initial UI.
 * General fields arranged and basic README colorization.

0.0.5 (2021-03-18)
 * First attempt at GitHub extraction.

[**cookiedough**(1)](https://fossil.include-once.org/cookiedough/file/manpage/cookiedough.md)
is a GUI browser for cookiecutter templates. It also allows for expanding them, of course.
It comes with a database of around 2300 cookietemplates, grouped by category, and allows some
rudimentary filtering. Very early alpha, but usable. 

![screenshot main window](https://imgur.com/wn9mEny.png)


# Installation / Use

Just install it as normal pip package:

    ~$   pip3 install -U cookiedough

And start it from a terminal window:

    ~/projects$   cookiedough

Keep an eye on the terminal when rolling out a template.


# Notes

There's some usage information in the man page. (Yes, there is a man page.)
And the application itself is somewhat self-explanatory.


## Bugs / Caveats

 * The search is still finicky. Right now it starts on any key press;
   [.. might either filter this by ENTER, or add a button to that effect].
 * Not all content fields expand to values. (PSG/Tk constrain the label
   widths on their initial length.)
 * The README colorization is fairly basic. (But more processsing would
   slow it down too much.)
 * It can crash when speed-scrolling through the templates. (Perhaps PSG
   vs Tk threads issue.)
 * Tkinter might also crash when encountering emojis. (Either install
   Symbola font and get rid of Noto Color Emoji. Or upgrade to tcl/tk
   8.6.10, or go back to Ubuntu 18.04 where it miraculously worked.)
 * No real help pages yet. Still too early, UI could change a bit.
   (ToDo: mkdocs2mallard)
 * No .desktop file (not sure if pip does such magic).


## Contributions

This project hinges on an updated cookiecutters database. Unfortunately
that's quite time-consuming. So new templates might not find their way
in here, without feedback/submissions from authors. (The preferred option
for now would be a full JSON blob as outlined below, per email).

If anyone wants to contribute, automating the compilation (and expanding
to BitBucket/GitLab, if a common GitHolm API / library ever emerges) would
be useful. Else perhaps a submission API using the repository (it's SQLite);
though that might still require moderation/approval/checks etc. (One could
use the [dev/ scripts](https://fossil.include-once.org/cookiedough/wiki/dev)
as basis; adding some application UI is easy.)

If interested, register a repository accont, drop a mail for developer elevation;
read up on [fossil usage](https://fossil-scm.org/home/doc/trunk/www/quickstart.wiki).
It's significantly easier than git, and you can't easily break things.


## uidata.json structure

The included cookiecutter database is based upon an extraction from GitHub,
filtered, and restructured for easier UI application. Entries typically
contain:

    "vnd/pkg": {
        "name": "vnd/pkg",
        "short": "pkg",
        "description": "...",
        "url": "https://github.com/vnd/pkg",
        "repo": "https://github.com/vnd/pkg.git",
        "homepage": null,
        "created_at": "2011-11-11T11:11:11Z",
        "updated_at": "2021-02-22T22:22:22Z",
        "size": 222,
        "stars": 2,
        "api": "lang",
        "has_wiki": true,
        "forks": 1,
        "license": "MIT",
        "tickets": 0,
        "default_branch": "trunk",
        "_disabled": false,
        "keywords": " from `_keywords` in cookiecutter.json ",
        "dir": "└── lib\n",
        "readme": "README.md contents",
        "cookiecutterjson_url": "https://raw.ghusrcnt/vnd/pkg/trunk/cookiecutter.json",
        "config": [
            {
                "type": "str",
                "name": "project_name",
                "value": "mypkg",
                "class": "cookiecutter",
                "description": " taken from README table, if any "
            }
        ]
    }

Most fields are literal copies. Whereas `dir` is a textual transformation
of the /tree list. And `config` a converted cookiecutter.json list. The
`api` field is either just GitHubs detected repository language (often
fairly off), or an extract from the repository name, or whatever was
specified as `_api` in cc.json.


### config

The config field list is an upmarket version of the cookiecutter.json dict.
Roughly compatible with the pluginconf structure. Albeit CD is using a
custom input window anyway.

Notably the `description` field cannot be set other than from the README.
It should contain a table listing each template variable:

          | `cc_varname` | Explanation ... |

(Seen some discussion on a cc.json 2.0 format. So this might be a temporary
thing. Still useful to users, btw!)


### Improve your cookiecutters.json

There will be some scoring scheme to sort the templates in CD. For the time
being, you can improve those by adding following properties:

| Where | Name | Usage |
------------------------
| `cookiecutters.json` | `_api` | Override the category/language (could be an app name, e.g. `flask`) |
| `cookiecutters.json` | `_keywords` | Add extra search keywords/tags |
| `README.*` | markdown table | Describe template variables |

(Why "scoring"? Because stars and forks are often just bandwagon votes, and
don't fully qualify the quality. They sometimes just make more contemporary
projects less visible. In pariticular when buried on Github.)

# type: function
# api: python
# title: help pages
# description: invokes yelp/mallard browser
# version: 0.1
#
# No pages to speak of yet.
#


import os, re

__dir__ = re.sub("[\w.-]+$", "", __file__)

def help():
    os.system(f"yelp %r &" % __dir__)

<page
    xmlns="http://projectmallard.org/1.0/"
    type="guide"
    id="index">

    <info>
        <link type="guide" xref="index#nav"/>
        
        <desc></desc>
    </info>

    <title>cookiedough</title>

<section>
 <title>cookiedough</title>
</section>

<section>
 <subtitle>cookiecutter browser GUI</subtitle>
 <list>
 <item><p>Available templates in the left pane</p></item>
 <item><p>Meta information, file list, and readme preview in the main section</p></item>
 <item><p>Installation button "Roll out" upper right hand</p></item>
 </list>
</section>


</page>

.\" Automatically generated by Pandoc 2.5
.\"
.TH "cookiecutter" "1" "" "cookiedough/cookiecutter" "Version 1.7"
.hy
.SH NAME
.PP
\f[B]cookiecutter\f[R] \[em] expands project templates
.SH SYNOPSIS
.PP
\f[B]cookiecutter\f[R] [\f[I]http://git\-repo/\f[R]]
.PP
\f[B]cookiecutter\f[R] [\f[I]./local\-template/\f[R]]
.SH DESCRIPTION
.PP
A command\-line utility that creates projects from cookiecutters
(project templates), e.g.\ creating a Python package project from a
Python package project template.
.SH USAGE
.SS Grab a Cookiecutter template
.PP
First, clone a Cookiecutter project template::
.IP
.nf
\f[C]
$ git clone git\[at]github.com:audreyr/cookiecutter\-pypackage.git
\f[R]
.fi
.SS Make your changes
.PP
Modify the variables defined in \f[C]cookiecutter.json\f[R].
.PP
Open up the skeleton project.
If you need to change it around a bit, do so.
.PP
You probably also want to create a repo, name it differently, and push
it as your own new Cookiecutter project template, for handy future use.
.SS Generate your project
.PP
Then generate your project from the project template::
.IP
.nf
\f[C]
$ cookiecutter cookiecutter\-pypackage/
\f[R]
.fi
.PP
The only argument is the input directory.
(The output directory is generated by rendering that, and it can\[cq]t
be the same as the input directory.)
.PP
\&..
note:: see :ref:\f[C]command_line_options\f[R] for extra command line
arguments
.PP
Try it out!
.SS Works directly with git and hg (mercurial) repos too
.PP
To create a project from the cookiecutter\-pypackage.git repo template::
.IP
.nf
\f[C]
$ cookiecutter gh:audreyr/cookiecutter\-pypackage
\f[R]
.fi
.PP
Cookiecutter knows abbreviations for Github (\f[C]gh\f[R]), Bitbucket
(\f[C]bb\f[R]), and GitLab (\f[C]gl\f[R]) projects, but you can also
give it the full URL to any repository::
.IP
.nf
\f[C]
$ cookiecutter https://github.com/audreyr/cookiecutter\-pypackage.git
$ cookiecutter git+ssh://git\[at]github.com/audreyr/cookiecutter\-pypackage.git
$ cookiecutter hg+ssh://hg\[at]bitbucket.org/audreyr/cookiecutter\-pypackage
\f[R]
.fi
.PP
You will be prompted to enter a bunch of project config values.
(These are defined in the project\[cq]s \f[C]cookiecutter.json\f[R].)
.PP
Then, Cookiecutter will generate a project from the template, using the
values that you entered.
It will be placed in your current directory.
.PP
And if you want to specify a branch you can do that with::
.IP
.nf
\f[C]
$ cookiecutter https://github.com/audreyr/cookiecutter\-pypackage.git \-\-checkout develop
\f[R]
.fi
.SS Works with private repos
.PP
If you want to work with repos that are not hosted in github or
bitbucket you can indicate explicitly the type of repo that you want to
use prepending \f[C]hg+\f[R] or \f[C]git+\f[R] to repo url::
.IP
.nf
\f[C]
$ cookiecutter hg+https://example.com/repo
\f[R]
.fi
.PP
In addition, one can provide a path to the cookiecutter stored on a
local server::
.IP
.nf
\f[C]
$ cookiecutter file://server/folder/project.git
\f[R]
.fi
.SS Works with Zip files
.PP
You can also distribute cookiecutter templates as Zip files.
To use a Zip file template, point cookiecutter at a Zip file on your
local machine::
.IP
.nf
\f[C]
$ cookiecutter /path/to/template.zip
\f[R]
.fi
.PP
Or, if the Zip file is online::
.IP
.nf
\f[C]
$ cookiecutter https://example.com/path/to/template.zip
\f[R]
.fi
.PP
If the template has already been downloaded, or a template with the same
name has already been downloaded, you will be prompted to delete the
existing template before proceeding.
.PP
The Zip file contents should be the same as a git/hg repository for a
template \- that is, the zipfile should unpack into a top level
directory that contains the name of the template.
The name of the zipfile doesn\[cq]t have to match the name of the
template \- for example, you can label a zipfile with a version number,
but omit the version number from the directory inside the Zip file.
.PP
If you want to see an example Zipfile, find any Cookiecutter repository
on Github and download that repository as a zip file \- Github
repository downloads are in a valid format for Cookiecutter.
.PP
Password\-protected Zip files
\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]
.PP
If your repository Zip file is password protected, Cookiecutter will
prompt you for that password whenever the template is used.
.PP
Alternatively, if you want to use a password\-protected Zip file in an
automated environment, you can export the
\f[C]COOKIECUTTER_REPO_PASSWORD\f[R] environment variable; the value of
that environment variable will be used whenever a password is required.
.SS Keeping your cookiecutters organized
.PP
As of the Cookiecutter 0.7.0 release:
.IP \[bu] 2
Whenever you generate a project with a cookiecutter, the resulting
project is output to your current directory.
.IP \[bu] 2
Your cloned cookiecutters are stored by default in your
\f[C]\[ti]/.cookiecutters/\f[R] directory (or Windows equivalent).
The location is configurable: see :doc:\f[C]advanced/user_config\f[R]
for details.
.PP
Pre\-0.7.0, this is how it worked:
.IP \[bu] 2
Whenever you generate a project with a cookiecutter, the resulting
project is output to your current directory.
.IP \[bu] 2
Cloned cookiecutters were not saved locally.
.SH DOCS
.IP \[bu] 2
Documentation: https://cookiecutter.readthedocs.io
.IP \[bu] 2
GitHub: https://github.com/cookiecutter/cookiecutter
.IP \[bu] 2
PyPI: https://pypi.python.org/pypi/cookiecutter
.SH FILES
.PP
Default paths are not XDG\-compliant
.TP
.B \f[B]\[ti]/.cookiecutterrc\f[R]
config store
.TP
.B \f[B]\[ti]/.cookiecutters/\f[R]
cache dir?
.PP
Note that \f[B]cookiedough\f[R](1) might override those settings.
.SH ENV
.TP
.B \f[B]COOKIECUTTER_CONFIG\f[R]
Location of YAML file to use in place of
\f[C]\[ti]/.cookiecutterrc\f[R].
Can also be specified per \f[I]\-\-config\-file\f[R] option.
.SH SEE ALSO
.PP
\f[B]cookiedough\f[R](1), \f[B]python3\f[R](1)

% cookiecutter(1) cookiedough/cookiecutter | Version 1.7


NAME
====

**cookiecutter** — expands project templates


SYNOPSIS
========

  **cookiecutter** \[*http://git-repo/*]

  **cookiecutter** \[*./local-template/*]


DESCRIPTION
===========

A command-line utility that creates projects from cookiecutters (project templates), e.g. creating a Python package project from a Python package project template.


USAGE
=====

Grab a Cookiecutter template
----------------------------

First, clone a Cookiecutter project template::

    $ git clone git@github.com:audreyr/cookiecutter-pypackage.git

Make your changes
-----------------

Modify the variables defined in `cookiecutter.json`.

Open up the skeleton project. If you need to change it around a bit, do so.

You probably also want to create a repo, name it differently, and push it as
your own new Cookiecutter project template, for handy future use.

Generate your project
---------------------

Then generate your project from the project template::

    $ cookiecutter cookiecutter-pypackage/

The only argument is the input directory. (The output directory is generated
by rendering that, and it can't be the same as the input directory.)

.. note:: see :ref:`command_line_options` for extra command line arguments

Try it out!



Works directly with git and hg (mercurial) repos too
------------------------------------------------------

To create a project from the cookiecutter-pypackage.git repo template::

    $ cookiecutter gh:audreyr/cookiecutter-pypackage

Cookiecutter knows abbreviations for Github (``gh``), Bitbucket (``bb``), and
GitLab (``gl``) projects, but you can also give it the full URL to any
repository::

    $ cookiecutter https://github.com/audreyr/cookiecutter-pypackage.git
    $ cookiecutter git+ssh://git@github.com/audreyr/cookiecutter-pypackage.git
    $ cookiecutter hg+ssh://hg@bitbucket.org/audreyr/cookiecutter-pypackage

You will be prompted to enter a bunch of project config values. (These are
defined in the project's `cookiecutter.json`.)

Then, Cookiecutter will generate a project from the template, using the values
that you entered. It will be placed in your current directory.

And if you want to specify a branch you can do that with::

    $ cookiecutter https://github.com/audreyr/cookiecutter-pypackage.git --checkout develop

Works with private repos
------------------------

If you want to work with repos that are not hosted in github or bitbucket you can indicate explicitly the
type of repo that you want to use prepending `hg+` or `git+` to repo url::

    $ cookiecutter hg+https://example.com/repo

In addition, one can provide a path to the cookiecutter stored
on a local server::

    $ cookiecutter file://server/folder/project.git

Works with Zip files
--------------------

You can also distribute cookiecutter templates as Zip files. To use a Zip file
template, point cookiecutter at a Zip file on your local machine::

    $ cookiecutter /path/to/template.zip

Or, if the Zip file is online::

    $ cookiecutter https://example.com/path/to/template.zip

If the template has already been downloaded, or a template with the same name
has already been downloaded, you will be prompted to delete the existing
template before proceeding.

The Zip file contents should be the same as a git/hg repository for a template -
that is, the zipfile should unpack into a top level directory that contains the
name of the template. The name of the zipfile doesn't have to match the name of
the template - for example, you can label a zipfile with a version number, but
omit the version number from the directory inside the Zip file.

If you want to see an example Zipfile, find any Cookiecutter repository on Github
and download that repository as a zip file - Github repository downloads are in
a valid format for Cookiecutter.

Password-protected Zip files
~~~~~~~~~~~~~~~~~~~~~~~~~~~~

If your repository Zip file is password protected, Cookiecutter will prompt you
for that password whenever the template is used.

Alternatively, if you want to use a password-protected Zip file in an
automated environment, you can export the `COOKIECUTTER_REPO_PASSWORD`
environment variable; the value of that environment variable will be used
whenever a password is required.

Keeping your cookiecutters organized
------------------------------------

As of the Cookiecutter 0.7.0 release:

* Whenever you generate a project with a cookiecutter, the resulting project
  is output to your current directory.

* Your cloned cookiecutters are stored by default in your `~/.cookiecutters/`
  directory (or Windows equivalent). The location is configurable: see
  :doc:`advanced/user_config` for details.

Pre-0.7.0, this is how it worked:

* Whenever you generate a project with a cookiecutter, the resulting project
  is output to your current directory.

* Cloned cookiecutters were not saved locally.


DOCS
====

 * Documentation: https://cookiecutter.readthedocs.io
 * GitHub: https://github.com/cookiecutter/cookiecutter
 * PyPI: https://pypi.python.org/pypi/cookiecutter


FILES
=====


**~/.cookiecutterrc**
 : config store

**~/.cookiecutters/**
 : cache dir?

These default paths are not XDG-compliant
(https://github.com/cookiecutter/cookiecutter/issues/104).

It's planned that **cookiedough**(1) overrides those settings,
or perhaps even silently moves + symlinks the cache dir and
config file.


ENV
===

**COOKIECUTTER_CONFIG**
 : Location of YAML file to use in place of `~/.cookiecutterrc`.  
 : Can also be specified per *\--config-file* option.


SEE ALSO
========

**cookiedough**(1), **python3**(1)

.\" Automatically generated by Pandoc 2.5
.\"
.TH "cookiedough" "1" "" "cookiedough/cookiecutter" "Version 0.1.x"
.hy
.SH NAME
.PP
\f[B]cookiedough\f[R] \[em] GUI browser for cookiecutter templates
.SH SYNOPSIS
.PP
\f[B]cookiedough\f[R] [\f[I]\-\-debug\f[R]]
.SH DESCRIPTION
.PP
Shows available project templates for \f[B]cookiecutter\f[R](1) in a GUI
browser.
Allows to inspect documentation and some contents, and then of course
unpack the template.
.SH USAGE
.SS Browsing
.IP \[bu] 2
Expand one of the categories in the left pane to see available
templates.
.IP \[bu] 2
Click to see expanded details on right pane.
.SS Search
.IP \[bu] 2
Click the search field, then perhaps select the real search field again.
.IP \[bu] 2
Any typing will trigger an update to the template list.
(Might fix this in a later release.)
.IP \[bu] 2
You might want to search for common keywords in the description, or even
filenames (\f[C]pyproject.toml setup.cfg\f[R] etc.) to find matching
cookiecutters.
.SS Install
.IP \[bu] 2
Push the [Roll out] button top right.
.IP \[bu] 2
Input any of the default placeholder variables, or update existing
sample strings.
You usually want to leave any \f[C]{{expression...}}\f[R] as is.
.IP \[bu] 2
Verify the current working directory, then proceed.
.IP \[bu] 2
Yes/No prompts or additional inputs might come up if the template list
was outdated.
.IP \[bu] 2
\f[B]WATCH OUT\f[R] for any prompts in the terminal window you started
cookiedough from.
Not all click prompts might get captured.
And obviously any error messages would gravitate there.
.SS Settings
.IP \[bu] 2
Use \[->]File\[->]Settings to modify some cookiedough UI behaviours.
.IP \[bu] 2
Some changes might require a restart.
.SH DOCS
.IP \[bu] 2
Project: https://fossil.include\-once.org/cookiedough/
.SH FILES
.TP
.B \f[B]\[ti]/.config/cookiedough/\f[R]
Application config files, specifically \f[I]settings.json\f[R].
Future versions
might also pack some \f[B]cookiecutter\f[R](1) yaml config file in here.
(Whereas the cache : would go into \f[I]\[ti]/.cache/\&...\f[R]).
.SH ENV
.TP
.B \f[B]XDG_CONFIG_HOME\f[R]
base dir location for app config storage
.TP
.B \f[B]GITHUB_API_TOKEN\f[R]
might or might not be used by update functionality
.SH SEE ALSO
.PP
\f[B]cookiecutter\f[R](1), \f[B]python3\f[R](1)

% cookiedough(1) cookiedough/cookiecutter | Version 0.1.x


NAME
====

**cookiedough** — GUI browser for cookiecutter templates

SYNOPSIS
========

  **cookiedough** \[*\--debug*]


DESCRIPTION
===========

Shows available project templates for **cookiecutter**(1) in a GUI browser.
Allows to inspect documentation and some contents, and then of course
unpack the template.

USAGE
=====

Browsing
--------

 * Expand one of the categories in the left pane to see available templates.
 * Click to see expanded details on right pane.

Search
------

 * Click the search field, then perhaps select the real search field again.
 * Any typing will trigger an update to the template list. (Might fix this
   in a later release.)
 * You might want to search for common keywords in the description, or
   even filenames (`pyproject.toml setup.cfg` etc.) to find matching
   cookiecutters.

Install
-------

 * Push the [Roll out] button top right.
 * Input any of the default placeholder variables, or update existing sample
   strings. You usually want to leave any `{{expression...}}` as is.
 * Verify the current working directory, then proceed.
 * Yes/No prompts or additional inputs might come up if the template list
   was outdated.
 * **WATCH OUT** for any prompts in the terminal window you started
   cookiedough from. Not all click prompts might get captured. And obviously
   any error messages would gravitate there.

Alternatives
------------

 * Apart from opening the URL for a cookietemplate, there is also the
   →Template→Copy repo URL option. Which allows to combine CD and CLI usage.

Settings
--------

 * Use →File→Settings to modify some cookiedough UI behaviours.
 * Some changes might require a restart.


DOCS
====

 * Project: https://fossil.include-once.org/cookiedough/


FILES
=====

**~/.config/cookiedough/**
 : Application config files, specifically *settings.json*.  Future versions
 : might also pack some **cookiecutter**(1) yaml config file in here. 
 : (Whereas the cache : would go into *~/.cache/...*).

ENV
===

**XDG_CONFIG_HOME**
 : base dir location for app config storage

**GITHUB_API_TOKEN**
 : might or might not be used by update functionality


SEE ALSO
========

**cookiecutter**(1), **python3**(1)