Copy in manual build of docs for typescript module draft

IntersectMBO · Jun 8, 2021 · 5167685 · 5167685
1 parent 14df949
commit 5167685
Show file tree

Hide file tree

Showing 20 changed files with 5,865 additions and 0 deletions.
diff --git a/typescript/assets/css/main.css b/typescript/assets/css/main.css
diff --git a/typescript/assets/images/icons.png b/typescript/assets/images/icons.png
diff --git a/typescript/assets/images/icons@2x.png b/typescript/assets/images/icons@2x.png
diff --git a/typescript/assets/images/widgets.png b/typescript/assets/images/widgets.png
diff --git a/typescript/assets/images/widgets@2x.png b/typescript/assets/images/widgets@2x.png
diff --git a/typescript/assets/js/main.js b/typescript/assets/js/main.js
diff --git a/typescript/assets/js/search.js b/typescript/assets/js/search.js
diff --git a/typescript/index.html b/typescript/index.html
@@ -0,0 +1,226 @@
+<!doctype html>
+<html class="default no-js">
+<head>
+	<meta charset="utf-8">
+	<meta http-equiv="X-UA-Compatible" content="IE=edge">
+	<title>cardano-addresses</title>
+	<meta name="description" content="Documentation for cardano-addresses">
+	<meta name="viewport" content="width=device-width, initial-scale=1">
+	<link rel="stylesheet" href="assets/css/main.css">
+	<script async src="assets/js/search.js" id="search-script"></script>
+</head>
+<body>
+<header>
+	<div class="tsd-page-toolbar">
+		<div class="container">
+			<div class="table-wrap">
+				<div class="table-cell" id="tsd-search" data-index="assets/js/search.json" data-base=".">
+					<div class="field">
+						<label for="tsd-search-field" class="tsd-widget search no-caption">Search</label>
+						<input id="tsd-search-field" type="text" />
+					</div>
+					<ul class="results">
+						<li class="state loading">Preparing search index...</li>
+						<li class="state failure">The search index is not available</li>
+					</ul>
+					<a href="index.html" class="title">cardano-addresses</a>
+				</div>
+				<div class="table-cell" id="tsd-widgets">
+					<div id="tsd-filter">
+						<a href="#" class="tsd-widget options no-caption" data-toggle="options">Options</a>
+						<div class="tsd-filter-group">
+							<div class="tsd-select" id="tsd-filter-visibility">
+								<span class="tsd-select-label">All</span>
+								<ul class="tsd-select-list">
+									<li data-value="public">Public</li>
+									<li data-value="protected">Public/Protected</li>
+									<li data-value="private" class="selected">All</li>
+								</ul>
+							</div>
+							<input type="checkbox" id="tsd-filter-inherited" checked />
+							<label class="tsd-widget" for="tsd-filter-inherited">Inherited</label>
+						</div>
+					</div>
+					<a href="#" class="tsd-widget menu no-caption" data-toggle="menu">Menu</a>
+				</div>
+			</div>
+		</div>
+	</div>
+	<div class="tsd-page-title">
+		<div class="container">
+			<h1>cardano-addresses</h1>
+		</div>
+	</div>
+</header>
+<div class="container container-main">
+	<div class="row">
+		<div class="col-8 col-content">
+			<div class="tsd-panel tsd-typography">
+				<a href="#cardano-addresses-typescript-binding" id="cardano-addresses-typescript-binding" style="color: inherit; text-decoration: none;">
+					<h1>cardano-addresses TypeScript binding</h1>
+				</a>
+				<p>This is a Typescript (or Javascript) version of the
+				<code>caardano-addresses</code> API. It comprises of three parts:</p>
+				<ul>
+					<li>The ghcjs build of <code>cardano-addresses:library</code> (supported by the
+					<code>cardano-addresses-jsbits</code> package.</li>
+					<li>A Cabal package <code>cardano-addresses-jsapi</code> containing GHCJS
+						foreign exports for translating Javascript function calls and
+					values into Haskell function calls and values, and vice-versa.</li>
+					<li>An NPM package <code>cardano-addresses</code> containing NodeJS modules written in TypeScript, which thinly wraps the GHCJS foreign exports to make a proper API.</li>
+				</ul>
+				<a href="#quick-start" id="quick-start" style="color: inherit; text-decoration: none;">
+					<h2>Quick Start</h2>
+				</a>
+				<a href="#nodejs-module-building-and-testing" id="nodejs-module-building-and-testing" style="color: inherit; text-decoration: none;">
+					<h3>NodeJS module: Building and testing</h3>
+				</a>
+				<p>Start a <code>nix-shell</code> in <em>this directory</em> (not the top-level) and run:</p>
+				<pre><code class="language-shell"><span style="color: #000000">$ </span><span style="color: #795E26">cd</span><span style="color: #000000"> jsapi</span>
+<span style="color: #000000">$ nix-shell</span>
+<span style="color: #000000">[nix-shell:~/iohk/cardano-addresses/jsapi]$ npm install &amp;&amp; npm run build</span>
+<span style="color: #000000">...</span>
+<span style="color: #000000">[nix-shell:~/iohk/cardano-addresses/jsapi]$ npm run </span><span style="color: #795E26">test</span>
+</code></pre>
+				<p>Behind the scenes, this will use Nix to make the <code>ghcjs</code> build of the <code>cardano-addresses</code> library. The path to this Javascript file is stored in the <code>$CARDANO_ADDRESSES_JSAPI</code> environment variable.</p>
+				<a href="#haskell-module-building-and-testing" id="haskell-module-building-and-testing" style="color: inherit; text-decoration: none;">
+					<h3>Haskell module: Building and testing</h3>
+				</a>
+				<p>To try it out run <code>nix-shell</code> from the repo top-level directory:</p>
+				<pre><code class="language-shell"><span style="color: #000000">$ nix-shell</span>
+<span style="color: #000000">[nix-shell:~/iohk/cardano-addresses]$ js-unknown-ghcjs-cabal build cardano-addresses-jsapi:unit</span>
+<span style="color: #000000">[nix-shell:~/iohk/cardano-addresses]$ node dist-newstyle/build/js-ghcjs/ghcjs-8.10.4/cardano-addresses-jsapi-3.5.0/t/unit/build/unit/unit.jsexe/all.js</span>
+</code></pre>
+				<p>That test initializes the api from a JS function that is called from <code>Main.hs</code>. To build <code>.js</code> file that might be easier to use from a JS app run:</p>
+				<pre><code class="language-shell"><span style="color: #000000">$ nix-build -A cardano-addresses-jsapi -o cardano-addresses.js</span>
+</code></pre>
+				<p>This replaces the regular <code>runmain.js</code> with <code>jsapi/glue/runmain.js</code>. That exposes a single function you can call and in a continuation.</p>
+				<p>To initialize call the <code>runCardanoAddressesApi</code> with a continuation that like the one in <code>jsapi/glue/test.js</code>. You will be passed <code>api</code> and <code>cleanup</code>.</p>
+				<a href="#more-details" id="more-details" style="color: inherit; text-decoration: none;">
+					<h2>More details</h2>
+				</a>
+				<a href="#nodejs-package" id="nodejs-package" style="color: inherit; text-decoration: none;">
+					<h3>NodeJS package</h3>
+				</a>
+				<p>For better or worse, this is based on the
+					<a href="https://github.com/palmerhq/tsdx">TSDX</a> template. The TSDX standard
+				documentation follows...</p>
+				<a href="#commands" id="commands" style="color: inherit; text-decoration: none;">
+					<h4>Commands</h4>
+				</a>
+				<p>To run TSDX, use:</p>
+				<pre><code class="language-bash"><span style="color: #000000">npm start </span><span style="color: #008000"># or yarn start</span>
+</code></pre>
+				<p>This builds to <code>/dist</code> and runs the project in watch mode so any edits you save inside <code>src</code> causes a rebuild to <code>/dist</code>.</p>
+				<p>To do a one-off build, use <code>npm run build</code> or <code>yarn build</code>.</p>
+				<p>To run tests, use <code>npm test</code> or <code>yarn test</code>.</p>
+				<a href="#configuration" id="configuration" style="color: inherit; text-decoration: none;">
+					<h4>Configuration</h4>
+				</a>
+				<p>Code quality is set up for you with <code>prettier</code>, and <code>lint-staged</code>. Adjust the respective fields in <code>package.json</code> accordingly.</p>
+				<a href="#jest" id="jest" style="color: inherit; text-decoration: none;">
+					<h5>Jest</h5>
+				</a>
+				<p>Jest tests are set up to run with <code>npm test</code> or <code>yarn test</code>.</p>
+				<a href="#bundle-analysis" id="bundle-analysis" style="color: inherit; text-decoration: none;">
+					<h5>Bundle Analysis</h5>
+				</a>
+				<p><a href="https://github.com/ai/size-limit"><code>size-limit</code></a> is set up to calculate the real cost of your library with <code>npm run size</code> and visualize the bundle with <code>npm run analyze</code>.</p>
+				<a href="#rollup" id="rollup" style="color: inherit; text-decoration: none;">
+					<h5>Rollup</h5>
+				</a>
+				<p>TSDX uses <a href="https://rollupjs.org">Rollup</a> as a bundler and generates multiple rollup configs for various module formats and build settings. See <a href="#optimizations">Optimizations</a> for details.</p>
+				<a href="#typescript" id="typescript" style="color: inherit; text-decoration: none;">
+					<h5>TypeScript</h5>
+				</a>
+				<p><code>tsconfig.json</code> is set up to interpret <code>dom</code> and <code>esnext</code> types, as well as <code>react</code> for <code>jsx</code>. Adjust according to your needs.</p>
+				<a href="#continuous-integration" id="continuous-integration" style="color: inherit; text-decoration: none;">
+					<h4>Continuous Integration</h4>
+				</a>
+				<a href="#github-actions" id="github-actions" style="color: inherit; text-decoration: none;">
+					<h3>GitHub Actions</h3>
+				</a>
+				<p>Two actions are added by default:</p>
+				<ul>
+					<li><code>tsdx-build</code> which installs deps w/ cache, lints, tests, and builds on all pushes against a Node and OS matrix</li>
+					<li><code>tsdx-size</code> which comments cost comparison of your library on every pull request using <a href="https://github.com/ai/size-limit"><code>size-limit</code></a></li>
+				</ul>
+				<a href="#optimizations" id="optimizations" style="color: inherit; text-decoration: none;">
+					<h4>Optimizations</h4>
+				</a>
+				<p>Please see the main <code>tsdx</code> <a href="https://github.com/palmerhq/tsdx#optimizations">optimizations docs</a>. In particular, know that you can take advantage of development-only optimizations:</p>
+				<pre><code class="language-js"><span style="color: #008000">// ./types/index.d.ts</span>
+<span style="color: #0000FF">declare</span><span style="color: #000000"> </span><span style="color: #0000FF">var</span><span style="color: #000000"> </span><span style="color: #001080">__DEV__</span><span style="color: #000000">: </span><span style="color: #267F99">boolean</span><span style="color: #000000">;</span>
+
+<span style="color: #008000">// inside your code...</span>
+<span style="color: #AF00DB">if</span><span style="color: #000000"> (</span><span style="color: #001080">__DEV__</span><span style="color: #000000">) {</span>
+<span style="color: #000000">  </span><span style="color: #001080">console</span><span style="color: #000000">.</span><span style="color: #795E26">log</span><span style="color: #000000">(</span><span style="color: #A31515">&#039;foo&#039;</span><span style="color: #000000">);</span>
+<span style="color: #000000">}</span>
+</code></pre>
+				<p>You can also choose to install and use <a href="https://github.com/palmerhq/tsdx#invariant">invariant</a> and <a href="https://github.com/palmerhq/tsdx#warning">warning</a> functions.</p>
+				<a href="#module-formats" id="module-formats" style="color: inherit; text-decoration: none;">
+					<h4>Module Formats</h4>
+				</a>
+				<p>CJS, ESModules, and UMD module formats are supported.</p>
+				<p>The appropriate paths are configured in <code>package.json</code> and <code>dist/index.js</code> accordingly. Please report if any issues are found.</p>
+				<a href="#publishing-to-npm" id="publishing-to-npm" style="color: inherit; text-decoration: none;">
+					<h4>Publishing to NPM</h4>
+				</a>
+				<p>TSDX recommend using <a href="https://github.com/sindresorhus/np">np</a>.</p>
+			</div>
+		</div>
+		<div class="col-4 col-menu menu-sticky-wrap menu-highlight">
+			<nav class="tsd-navigation primary">
+				<ul>
+					<li class=" ">
+						<a href="modules.html">Exports</a>
+					</li>
+					<li class=" tsd-kind-module">
+						<a href="modules/cardano_addresses.html">cardano-<wbr>addresses</a>
+					</li>
+					<li class=" tsd-kind-module">
+						<a href="modules/cli.html">cli</a>
+					</li>
+					<li class=" tsd-kind-module">
+						<a href="modules/index.html">index</a>
+					</li>
+					<li class=" tsd-kind-module">
+						<a href="modules/library.html">library</a>
+					</li>
+					<li class=" tsd-kind-module">
+						<a href="modules/types.html">types</a>
+					</li>
+					<li class=" tsd-kind-module">
+						<a href="modules/version.html">version</a>
+					</li>
+				</ul>
+			</nav>
+			<nav class="tsd-navigation secondary menu-sticky">
+				<ul class="before-current">
+				</ul>
+			</nav>
+		</div>
+	</div>
+</div>
+<footer class="with-border-bottom">
+	<div class="container">
+		<h2>Legend</h2>
+		<div class="tsd-legend-group">
+			<ul class="tsd-legend">
+				<li class="tsd-kind-variable"><span class="tsd-kind-icon">Variable</span></li>
+				<li class="tsd-kind-function"><span class="tsd-kind-icon">Function</span></li>
+				<li class="tsd-kind-type-alias"><span class="tsd-kind-icon">Type alias</span></li>
+			</ul>
+			<ul class="tsd-legend">
+				<li class="tsd-kind-interface"><span class="tsd-kind-icon">Interface</span></li>
+			</ul>
+		</div>
+	</div>
+</footer>
+<div class="container tsd-generator">
+	<p>Generated using <a href="https://typedoc.org/" target="_blank">TypeDoc</a></p>
+</div>
+<div class="overlay"></div>
+<script src="assets/js/main.js"></script>
+</body>
+</html>