# Note this requires a bit of post-editing.
# The titles from the fossil wiki have a redundant prefix,
# and the first <title> might be empty even, or else even duplicated.

pages:
	html2mallard https://fossil.include-once.org/cookiedough/wiki/contribute > contribute.page
	html2mallard https://fossil.include-once.org/cookiedough/wiki/improve > improve.page
	html2mallard https://fossil.include-once.org/cookiedough/wiki/rollout > rollout.page
	html2mallard https://fossil.include-once.org/cookiedough/wiki/search > search.page
	html2mallard https://fossil.include-once.org/cookiedough/wiki/settings > settings.page
	html2mallard https://fossil.include-once.org/cookiedough/wiki/usage > usage.page

desc:
	# fix default extractions
	fr '<desc></desc>' '<desc>todo list, dev/ scripts, fossil, cookiecutter authors</desc>'  contribute.page
	fr '<desc></desc>' '<desc>template vars, extra parameters for cookiedough</desc>' improve.page
	fr '<desc></desc>' '<desc>project overview</desc>' index.page
	fr '<desc></desc>' '<desc>available features</desc>' menu.page
	fr '<desc></desc>' '<desc>XDG patch and paths</desc>' patch.page
	fr '<desc></desc>' '<desc>installation of tempaltes, input prompts</desc>' rollout.page
	fr '<desc></desc>' '<desc>filter options</desc>' search.page
	fr '<desc></desc>' '<desc>config options per module</desc>' settings.page
	fr '<desc></desc>' '<desc>internal tempalte database, config[] format</desc>' uidata.page
	fr '<desc></desc>' '<desc>start, browsing, search, roll out</desc>' usage.page
	fr '<title>cookiedough: ' '<title>' *.page
	fr '<title>contribute</title>' '<title>How to contribute / ToDo</title>' contribute.page
	fr '<title>improve</title>' '<title>Improve your cookiecutter.json</title>' improve.page
	fr '<title>menu</title>' '<title>Menu structure</title>' menu.page
	fr '<title>patch</title>' '<title>Cookiecutter patch</title>' patch.page
	fr '<title>rollout</title>' '<title>Roll out</title>' rollout.page:
	fr '<title>search</title>' '<title>Search bar</title>' search.page
	fr '<title>uidata</title>' '<title>internal "database" structure</title>' uidata.page

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

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

    <desc>todo list, dev/ scripts, fossil, cookiecutter authors</desc>
    <?http header="X-Generator: html2mallard" ?>
</info>

<title>How to contribute / ToDo</title>


<section>
 <title>Contributions</title>
 <p>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.</p>

 <p>Not sure if there's enough interest, but this would require either
 automating the database build, or providing a submission API. Or both.</p>
</section>

<section>
 <subtitle>Automation</subtitle>
 <list>

 <item><p>There's the <link type="seealso" href="https://fossil.include-once.org/cookiedough/wiki/dev">dev/ scripts</link>
 as basis.</p></item>
 <item><p>Ideally it would be rewritten to also support BitBucket/GitLab/etc.


 The lack of common API is a real showstopper though.</p></item>
 <item><p>(I don't blame GitHub alone.)</p></item>
 <item><p>And obviously there's no library that interfaces with all alike.</p></item>
 </list>
 <item><p>Wouldn't be too difficult to bring this into the GUI even. (Though it
 takes around half an hour to collect project repositories on GH.)</p></item>

</section>

<section>
 <subtitle>Submit API</subtitle>
 <list>

 <item><p>It might be easiest to query individual projects, and just provide a
 submission endpoint.</p></item>
 <item><p>The fossil repository is SQLite-based, so would allow nearby storage.</p></item>
 <item><p>Albeit you would still need a moderation step, rather than automatic
 updates for the main uidata.json.</p></item>
 <item><p>Or possibly just use the fossil ticket or forum feature.


 In which case, you could help out by reviewing/approving tickets.</p></item>
 </list>
</section>

<section>
 <subtitle>Join</subtitle>
 <list>

 <item><p>If interested, register a repository account here (no email necessary).</p></item>
 <item><p>Drop a mail for developer elevation;</p></item>
 <item><p>Read up on <link type="seealso" href="https://fossil-scm.org/home/doc/trunk/www/quickstart.wiki">fossil usage</link>.</p></item>
 <item><p>It's significantly easier than git, and you can't easily break things.</p></item>
 </list>
</section>

<section>
 <subtitle>Manual submissions</subtitle>
 <p>For now: you can send in a full JSON blob per email (see
 LICENSE), if you want your template be updated or added.</p>
</section>

  




  



</page>

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

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

    <desc>template vars, extra parameters for cookiedough</desc>
    <?http header="X-Generator: html2mallard" ?>
</info>

<title>Improve your cookiecutter.json</title>


<section>
 <subtitle>Supported additions for cookiecutter.json</subtitle>
 <p>cookiedough accepts some additional fields from <code>cookiecutters.json</code>. This
 helps both the parameter input, as well as grouping, search and scoring/sorting
 of entries.</p>

 <p>Currently following options are recognized:</p>

 <table shade="rows cols" rules="rows cols"><tbody>

   <tr>
         <td><p>Where</p></td>
         <td><p>Name</p></td>
         <td><p>Usage</p></td>
   </tr>


   <tr>
         <td><p><code>cookiecutter.json</code></p></td>
         <td><p><code>_api</code></p></td>
         <td><p>Override the category/language (could be an app name, e.g. <code>flask</code>)</p></td>
   </tr>
   <tr>
         <td><p><code>cookiecutter.json</code></p></td>
         <td><p><code>_keywords</code></p></td>
         <td><p>Add extra search keywords/tags (comma/space-separated string)</p></td>
   </tr>
   <tr>
         <td><p><code>cookiecutter.json</code></p></td>
         <td><p><code>_requirements</code></p></td>
         <td><p>Build dependencies (a JSON list), for example <code>["poetry", "pipenv", "pluginconf"]</code></p></td>
   </tr>
   <tr>
         <td><p><code>cookiecutter.json</code></p></td>
         <td><p><code>_license</code></p></td>
         <td><p>License of the cookiecutter template files. Ideally ought to be "PD" or "CC0". If attribution/academic licsense ("MITL" or "BDSL"), the template should note itself in the generated README or CREDITS, etc. -- <em style="strong">Note</em>: license of the cookiecutter repository (that's what the GH API yields) can/should divert from the license of the actual template files.</p></td>
   </tr>
   <tr>
         <td><p><code>README.*</code></p></td>
         <td><p>markdown</p></td>
         <td><p>Describe all template variables, using a "❙<code>varname</code>❙Explanation...❙" table</p></td>
   </tr>

 </tbody></table>

 <p>For example:</p>

 <code> {
      "project_slug": "base-name",
      "_api": "django",
      "_keywords": "make-whl, xdg, pytest, mkdocs",
      "_license": "CC0",
      "_requirements": ["poetry", "pep517"]
  }
 </code>

 <p>Whereas your README should contain explanations for template vars:</p>

 <code> | Variable       | Explanation ...                        |

 are simply accrued for older projects. It's often just bandwagon voting even.</p>

 <p>Instead cookiedough takes multiple properties into account, and somewhat
 weighs them against each other. Average projects are favoured, and some
 contents rewarded. It's not a huge influence, but hopefully brings more
 contemporary templates to the top.</p>

 <p>See settings or cookiedough/update.py
 on how the default scoring works. (This is going to be come more configurable.)</p>
</section>

  




  



</page>

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

    <info>
        <desc>project overview</desc>
    </info>

<title>cookiecutter browser GUI</title>
<p>A browser and installation tool for cookiecutter templates.</p>

<section id="nav" style="2column">
 <subtitle>Topics</subtitle>

 <item><p>Available templates can be selected in the left pane.</p></item>
 <item><p>Meta information, file list, and readme preview in the main section.</p></item>
 <item><p>The installation button "Roll out" is located in the upper right.</p></item>
 </list>
</section>


<section id="else"> <subtitle>Other</subtitle> <p>More info possibly on
<link
href="https://fossil.include-once.org/cookiedough/">https://fossil.include-once.org/cookiedough/</link>.</p>
</section>

</page>

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

<info>
    <link type="guide" xref="index#nav"/>
    <link type="topic" xref="usage"/>
    <desc>available features</desc>
    <?http header="X-Generator: html2mallard" ?>
</info>

<title>Menu structure</title>


          
<section>
 <title>Menu structure</title>
          





 


 <p>The current menu structure is as follows:</p>

 <table shade="rows cols" rules="rows cols"><tbody>

   <tr>
         <td><p>Menu</p></td>

         <td><p>application info</p></td>
   </tr>

 </tbody></table>
</section>

  




  



</page>

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

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

    <desc>XDG patch and paths</desc>
    <?http header="X-Generator: html2mallard" ?>
</info>

 <title>Cookiecutter patch</title>


<section>
 <p>cookiedough provides a mneu option →File→Cookiecutter→Patch for XDG-compliance,
 which permanently fixes cookiecutters´ config module to use a <code>~/.config</code> path.</p>
 <list>
 <item><p>The new config filename will be <code>~/.config/cookiecutter/config</code>.</p></item>
 <item><p>It'll also move an existing cache and replay/ directories.</p></item>
 <item><p>Incurs a dependency on the <code>appdirs</code> package.</p></item>
 <item><p>Patch will create a <code>config.py.orig</code>, so it's easily reversible.</p></item>
 </list>
 <p>When used from within cookiedough, the old cookiecutter paths would be ignored
 in any case. (Fixated options). This patch is meant to bring CLI usage in line
 with GUI invocations.</p>
</section>

<section>
 <subtitle>The prophecy of a clutter-free homedir</subtitle>
 <p>System tools having a config file ~/.bashrc, ~/.ssh or even ~/.firefox directly
 in the homedir is perfectly fine. Special-purpose and rarely used development 
 tools are not entitled to such. And it went a little out of hand lately. (I blame
 git, as is custom.)</p>
 <p>User land applications should honor the XDG spec, APPDATA or whatever MacOS uses.
 And this includes CLI tools. Which is why cookiedough enforces it for cookiecutter.</p>
</section>


</page>

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

<info>
    <link type="guide" xref="index#nav"/>
    <link type="topic" xref="usage"/>
    <desc>installation of tempaltes, input prompts</desc>
    <?http header="X-Generator: html2mallard" ?>
</info>

<title>Roll out</title>

          
<section>

 <p>Created project directories will usually reside below the current working
 directory. To verify or change your current location, use the <em style="strong">chdir</em>
 button.</p>

 <p><em style="strong">WATCH OUT</em> for any prompts in the terminal window you started
 cookiedough from. Not all click prompts might get captured. And
 obviously any error messages would show up there.</p>

 <note style="bug"><p>If a OutputDirExistsException or ImportError occurs,
 cookiedough will crash alongside cookiecutter. Makes no sense to capture
 or shorten error messages for what's essentially a programming tool.</p></note>
</section>


</page>

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

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

    <desc>filter options</desc>
    <?http header="X-Generator: html2mallard" ?>
</info>

<title>Search bar</title>


          
<section>

 <p>Click the search field top left. Due to the current implementation you

 might have to refocus on the actual input widget.</p>



 <p>Any typing will trigger an update to the template list. (Might fix this
 in a later release.)</p>

 <p>You might want to search for common keywords in the description, or
 even filenames.</p>

 <list>

 <item><p>Allows to search multiple items at once: <code>pyproject.toml setup.cfg</code></p></item>
 <item><p>You can also enter regexen here, <code>py\w+\.py</code> for example.</p></item>
 <item><p>The search will scan the readme, file list, _keywords,
 template variables, and template names.</p></item>
 </list>

 <p>To reset the search filter you currently have to backspace all input
 in the field.</p>

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

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

    <desc>config options per module</desc>
    <?http header="X-Generator: html2mallard" ?>
</info>

<title>Settings</title>


          
<section>
 <p>Use →File→Settings to access the cookiedough options menu.</p>

 <list>

 <item><p>Options are grouped by modules there.</p></item>
 <item><p>Some may only take effect after a restart (e.g. hook_prompt).</p></item>
 <item><p>Stored in ~/.config/cookiedough/settings.json.</p></item>
 <item><p>There is no plugin handling in CD, so ticking the modules has no effect.</p></item>
 </list>
</section>

<section>

         <td><p>name</p></td>
         <td><p>avg/weight</p></td>
         <td><p>description</p></td>
   </tr>


   <tr>
         <td><p><em style="strong">all</em></p></td>
         <td><p>= 5.0</p></td>
         <td><p>cumulative weighted score</p></td>
   </tr>
   <tr>





         <td><p>size</p></td>
         <td><p>64</p></td>
         <td><p>overall size of repository (in kb)</p></td>
   </tr>
   <tr>
         <td><p>stars</p></td>
         <td><p>20</p></td>
         <td><p>project watchers/stars</p></td>
   </tr>
   <tr>
         <td><p>forks</p></td>
         <td><p>5</p></td>
         <td><p>number of github forks</p></td>
   </tr>
   <tr>
         <td><p>tickets</p></td>
         <td><p>10</p></td>
         <td><p>number of open tickets in repo</p></td>
   </tr>
   <tr>
         <td><p>vars</p></td>
         <td><p>7</p></td>
         <td><p>number of templating variables</p></td>
   </tr>
   <tr>
         <td><p>files</p></td>
         <td><p>32</p></td>
         <td><p>number of files in template</p></td>
   </tr>
   <tr>
         <td><p>readme</p></td>
         <td><p>2048</p></td>
         <td><p>length of README</p></td>
   </tr>
   <tr>
         <td><p>lang</p></td>
         <td><p>-0.9</p></td>
         <td><p>non-english text</p></td>
   </tr>
   <tr>
         <td><p>age</p></td>
         <td><p>9 months</p></td>
         <td><p>age of last release</p></td>
   </tr>
   <tr>
         <td><p><em style="strong">bonus</em></p></td>





         <td><p>+2.5</p></td>
         <td><p>tree listing, keywords, curated, descriptions</p></td>
   </tr>
   <tr>
         <td><p>curated</p></td>
         <td><p>+0.8</p></td>
         <td><p>previously listed in CC README</p></td>
   </tr>
   <tr>
         <td><p>keywords</p></td>
         <td><p>+0.5</p></td>
         <td><p>has a _keywords field</p></td>
   </tr>
   <tr>
         <td><p>descriptions</p></td>
         <td><p>+1.25</p></td>
         <td><p>contains field descriptions in README</p></td>
   </tr>
   <tr>
         <td><p>score.find</p></td>
         <td><p>+0.5*len</p></td>
         <td><p>additional content/filenames to reward</p></td>
   </tr>

 </tbody></table>

 <p>Note that alphabetically sorting works best with the "short" project name, while the "name" represents the vnd/pkg title, so won't look very sorted in the tree list. Take note of →Template→Details to see how the scoring works on each entry (usually at the bottom).</p>



 <p>Not all fields are selectable in the config window. (Though you could edit the <code>~/.config/cookiedough/settings.json</code>)</p>
</section>

<section>
 <subtitle>no_params / hook_prompt</subtitle>
 <p>Enabling <em style="strong">no_params</em> will avoid the input window when rolling out a
 teplate.</p>

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

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

    <desc>internal tempalte database, config[] format</desc>
    <?http header="X-Generator: html2mallard" ?>
</info>

<title>technical: uidata.json format</title>

          
<section>
 <title>internal "database" structure</title>
 <p>The included cookiecutter database is based upon an extraction from GitHub,
 filtered, and restructured for easier UI application. Entries typically
 contain:</p>

 <code>"vnd/pkg": {
     "name": "vnd/pkg",
     "short": "pkg",

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

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

    <desc>start, browsing, search, roll out</desc>
    <?http header="X-Generator: html2mallard" ?>
</info>

<title>Usage overview</title>


          
<section>


 <p>Start cookiedough from the terminal, in your <code>~/projects</code> directory:</p>

 <code>$  cookiedough
 </code>

 <p>You can browse the tempalte list in the left pane. They're grouped

 version of the repository instead. Alterantively use →Template→Copy
 repo URL to utilize the URL to use with commandline cookiecutter.</p>

 <p>Hitting the Roll out button will start the creation
 process. (Though a template variables input window will appear
 beforehand.)</p>
</section>

  




  



</page>

.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 OPTIONS
.PP
The \f[I]TEMPLATE\f[R] parameter can either be a remote repository
\f[I]http://git.example.com/co.git\f[R] (only Git/Mercurial supported),
a local checkout \f[I]./local\-template/\f[R], the name of any
\f[I]previously\-ran\-template\f[R], and a local or remote zip file
\f[I]http://fsl.example.com/repo.zip\f[R] even.
.TP
.B \-V, \-\-version
Show the version and exit.
.TP
.B \-\-no\-input
Do not prompt for parameters and only use cookiecutter.json file content
.TP

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)
.SH AUTHORS
cookiecutter project (audreyfeldroy, freakboy3742, stevepiercy,
terryjbates, pokoli, saxix, hackebrot, pfmoore, macrotim, kmike,
foobacca, luzfcb, ivanovmg), (c) BSDL\-3.

% cookiecutter(1) cookiedough/cookiecutter | Version 1.7
% cookiecutter project (audreyfeldroy, freakboy3742, stevepiercy, terryjbates, pokoli, saxix, hackebrot, pfmoore, macrotim, kmike, foobacca, luzfcb, ivanovmg), (c) BSDL-3


NAME
====

**cookiecutter** — expands project templates

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


OPTIONS
=======

The *TEMPLATE* parameter can either be
a remote repository *http://git.example.com/co.git* (only Git/Mercurial supported),
a local checkout *./local-template/*,
the name of any *previously-ran-template*,
and a local or remote zip file *http://fsl.example.com/repo.zip* even.

-V, -\-version
: Show the version and exit.

-\-no-input
: Do not prompt for parameters and only use cookiecutter.json file content