Discuss Build and Formalize Build Scripts

[ctcncgr]

We need to discuss the current packaging and rollup and decide if we want to proceed with this or redesign it.

tsc && rollup -c rollup.config.js

[sammyjava]

I can't imagine myself having an opinion. Happy to do as I'm told. :)

[alancleary]

This isn't directly related to the build process but I've been thinking UIkit probably shouldn't be included when the web components are built/bundled because it's already part of the Jekyll site and the version included in the Jekyll site is actually being built as part of the site's theme so we can customize colors, etc via the _config.yml file. So if we included UIkit in the web component build it wouldn't be the consistent with the Jekyll site.

I don't think excluding UIkit should be a problem from the web component build perspective since we're just using its CSS elements. It would be a different story if we were using UIkit JS/TS code within our web component code.

[ctcncgr]

We have decided that complex dependencies that may rollup into very large bundles, dependencies with no typing files (not trivial to generate) or those written in commonJS, will be external dependencies and will be included using the 'declare' keyword. UIkit is assumed to be available for all components (for now we only use this in the markup) as well as all other declared namespaces. It will be important to have good docs for these types of dependencies.

[alancleary]

It will be important to have good docs for these types of dependencies.

The documentation framework I've been working on is built using TypeDoc, which supports defining custom tags for use in JSDoc comments. We could use this to define external dependencies, resulting in them being given their own explicit section in a component's documentation when the tag is used. @ctcncgr Would this be sufficient for the non-bundled dependencies? Here's an example of the custom tag being defined and used for our custom HTMLElements.

[ctcncgr]

@alancleary, I think this would work.

Something like:

{
    "extends": ["typedoc/tsdoc.json"],
    "tagDefinitions": [
        {
            "tagName": "@phylotreeDependencies",
            "syntaxKind": "block"
        }
    ]
}

Then something like?

/**
 * @htmlElement `<lis-phylotree-element>`
 *
 * A Web Component that accepts newick and a name and returns a rendered tree
 * .
 * .
 * .
 * External Dependencies
 * @phylotreeDependencies
 * Text about D3 and TnT
 * Script tags for D3 and TnT
 * 

[alancleary]

@ctcncgr That's a little too specific. Tags are supposed to be generic so they can be used in different contexts. For example, the @htmlElement tag I previously mentioned is also used by the pagination, search, and table components. Also, tags can be used more than once within a single JSDoc comment so it would probably make sense to make the tag singular instead of plural and use it multiple times if there's more than one external dependency.

{
    "extends": ["typedoc/tsdoc.json"],
    "tagDefinitions": [
        {
            "tagName": "@externalDependency",
            "syntaxKind": "block"
        }
    ]
}

It's probably worth including the external dependencies in the HTML examples as well in case people decide to just copy-paste the examples instead of reading the docs :roll_eyes:

/**
 * @htmlElement `<lis-phylotree-element>`
 *
 * @externalDependency {@link https://d3js.org/ | D3}
 * @externalDependency {@link https://tntvis.github.io/tnt/ |  TnT}
 *
 * A Web Component that accepts newick and a name and returns a rendered tree.
 *
 * @example
 * The phylotree element in action:
 * ```html
 * <!-- D3 -->
 * <script src="http://d3js.org/d3.v3.min.js" charset="utf-8"></script>
 *
 * <!-- TnT -->
 * <link rel="stylesheet" href="http://tntvis.github.io/tnt/build/tnt.css" type="text/css" />
 * <script src="http://tntvis.github.io/tnt/build/tnt.min.js" charset="utf-8"></script>
 * 
 * <!-- the phylotree component -->
 * <lis-phylotree-element id="phylotree"></lis-phylotree-element>
 *
 * <!--configure the phylotree component via JavaScript -->
 * <script type="text/javascript">
 *   // get the phylotree element
 *   const phylotreeElement = document.getElementById('phylotree');
 *   // do stuff...
 * ```
 * 
 * ...
 *
 */