-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathbootstrapping_with_cmt.html
122 lines (122 loc) · 6.26 KB
/
bootstrapping_with_cmt.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
<!DOCTYPE html>
<html lang="en-US">
<head>
<title>CMTools</title>
<link rel="stylesheet" href="/css/site.css">
</head>
<body>
<nav>
<ul>
<li><a href="/">Home</a></li>
<li><a href="index.html">README</a></li>
<li><a href="LICENSE">LICENSE</a></li>
<li><a href="INSTALL.html">INSTALL</a></li>
<li><a href="user_manual.html">User Manual</a></li>
<li><a href="about.html">About</a></li>
<li><a href="search.html">Search</a></li>
<li><a href="https://github.com/caltechlibrary/CMTools">GitHub</a></li>
</ul>
</nav>
<section>
<h1
id="bootstrapping-a-typescript-project-with-codemeta-tools">Bootstrapping
a TypeScript project with CodeMeta Tools</h1>
<p>While Deno provides most tooling for bootstrapping a TypeScript
project there are some things it doesn’t handle directly. In my Caltech
Library project I like to include a CITATION.cff, about.md and have a
simple Pandoc template for generating the website for the project. These
can all be accomplished with CodeMeta Tools’ <code>cmt</code>
command.</p>
<h2 id="typical-tasks">Typical Tasks</h2>
<p>In the old days I’d so this for a TypeScript project setup.</p>
<ol type="1">
<li>create a directory to hold your project change into that
directory</li>
<li>Run <code>git init</code> in the directory</li>
<li>Run <code>deno init</code> in the directory</li>
<li>Write a basic README.md, INSTALL.md and copy in the appropriate
LICENSE file</li>
<li>Create a codemeta.json file</li>
<li>Create an about.md page</li>
<li>Create a Pandoc template (e.g. page.tmpl)</li>
<li>Create a CITATION.cff file</li>
<li>Create a version.ts file for the project version, Git hash and
license info</li>
<li>Start documenting and coding your project.</li>
</ol>
<p>Here’s the commands I’d run in my shell to accomplish these
tasks.</p>
<pre class="shell"><code>mkdir myproject && cd myproject
git init
deno init
touch README.md INSTALL.md
cp ../<SOME_OTHER_PROJECT>/LICENSE ./
# Edit the three files.
micro README.md INSTALL.md LICENSE
firefox https://codemeta.github.io/codemeta-generator/
# paste the result into my codemeta.json file
micro codemeta.json
# create an about page from the codemeta.json contents
micro about.md
# copy then edit a Pandoc template for building website
cp ../<SOME_OTHER_PROJECT>/page.tmpl ./
micro page.tmpl
codemeta2cff
# I usually write a Makefile to generate version.ts
# and other artifacts. NOTE: Makefile doesn't work on Windows
micro Makefile
make version.ts</code></pre>
<p>Now I am ready to start code the project. The copy edit approach can
be improved using GitHub repository templates but I’ve found editing
often took as long as just writing the documents from scratch (exception
is LICENSE file). Additionally relying on Makefile means to develop on
Windows I must install a whole POSIX stack or limit myself to using the
Linux Subsystem for Windows. While both Go and Deno both are good at
cross compilation if the rest of your build environment requires POSIX
then that forces you to POSIX for basic development. This is less than
ideal.</p>
<h2
id="simplifying-the-bootstrap-using-deno-tasks-and-codemeta-tools">Simplifying
the bootstrap using Deno tasks and CodeMeta Tools</h2>
<p>Steps one through four remaining the same. Step five is easy as using
the <a href="https://codemeta.github.io/codemeta-generator/">CodeMeta
Generator</a>. Steps six through nine in the past have meant either
copying and editing scripts to generate the content or manually creating
the content. With <code>cmt</code> you just need to run a single command
for each of the targeted files. Here’s the steps adjusted to use
cmt.</p>
<p>The basic steps.</p>
<pre class="shell"><code>mkdir myproject && cd myproject
git init
deno init
touch README.md INSTALL.md
cp ../<SOME_OTHER_PROJECT>/LICENSE ./
# Edit the three files.
micro README.md INSTALL.md LICENSE
firefox https://codemeta.github.io/codemeta-generator/
# paste the result into my codemeta.json file
micro codemeta.json</code></pre>
<p>Now you shortcut the rest of the effort using generated content with
<code>cmt</code>. For TypeScript that would look like.</p>
<pre class="shell"><code>cmt codemeta.json about.md page.tmpl CITATION.cff version.ts</code></pre>
<p>NOTE: You can individual create the files using <code>cmt</code> like
this.</p>
<p>For deno projects you can also generate tasks to manage your project
with the <code>--deno</code> option as the last command line
parameter.</p>
<pre class="shell"><code>cmt codemeta.json version.ts about.md CITATION.cff --deno</code></pre>
<p>This would result in a deno.json task element like the following.</p>
<div class="sourceCode" id="cb5"><pre
class="sourceCode json"><code class="sourceCode json"><span id="cb5-1"><a href="#cb5-1" aria-hidden="true" tabindex="-1"></a><span class="fu">{</span></span>
<span id="cb5-2"><a href="#cb5-2" aria-hidden="true" tabindex="-1"></a> <span class="dt">"tasks"</span><span class="fu">:</span> <span class="fu">{</span></span>
<span id="cb5-3"><a href="#cb5-3" aria-hidden="true" tabindex="-1"></a> <span class="dt">"gen-code"</span><span class="fu">:</span> <span class="st">"deno task version.ts ; deno task about.md ; deno task CITATION.cff"</span><span class="fu">,</span></span>
<span id="cb5-4"><a href="#cb5-4" aria-hidden="true" tabindex="-1"></a> <span class="dt">"version.ts"</span><span class="fu">:</span> <span class="st">"cmt codemeta.json version.ts"</span><span class="fu">,</span></span>
<span id="cb5-5"><a href="#cb5-5" aria-hidden="true" tabindex="-1"></a> <span class="dt">"about.md"</span><span class="fu">:</span> <span class="st">"cmt codemeta.json about.ts"</span><span class="fu">,</span></span>
<span id="cb5-6"><a href="#cb5-6" aria-hidden="true" tabindex="-1"></a> <span class="dt">"CITATION.cff"</span><span class="fu">:</span> <span class="st">"cmt codemeta.json CITATION.cff"</span></span>
<span id="cb5-7"><a href="#cb5-7" aria-hidden="true" tabindex="-1"></a> <span class="fu">}</span></span>
<span id="cb5-8"><a href="#cb5-8" aria-hidden="true" tabindex="-1"></a><span class="fu">}</span></span></code></pre></div>
<p>This means I can run <code>deno task gen-code</code> to update these
files when I update my codemeta.json.</p>
</section>
</body>
</html>