cp-ts-launchpad-v2-doco

A Captivate project starting point for 2022. But now with a doco site, CI testing and automated publish to NPM!

Git commits

Open a new branch (preferabaly through a GitHub Issue) and make small commits. When you want to add a commit, run the following:

git add .
yarn commit

This will step you through a short CLI which will confirm what kind of changes have been made.

Once you're ready to release to NPM, create a pull request to Main. The CI will first run the Cypress tests to confirm no errors have snuck in. After that, when you accept the pull request, GitHub Actions will automatically change the package.json version number and then push the new build to the npm registry.

Cypress tests

Cypress has been set up with TypeScript. A local host server has been set up to serve the 'server/' folder to port 3000. The server/ folder has been pre-populated with some Captivate test projects.

You can begin running the localhost test server and the Cypress tests with the following command:

yarn test

Within Cypress, the cy.testInCpVersions command has been added to allow you to quickly run tests in different versions of Captivate

it("adds", () => {

	cy.testInCpVersions(["BLANK", "CP_0_2019_REGULAR", "CP_0_2019_RESPONSIVE"], () => {

		// The following code will be run in the above 3 test fixture environments.
		cy.wrap(add(1, 2)).should("eq", 3);

	});

});

Doc site setup

On creating a new project, please got to the docusaurus.config.js and edit the entries with the comment...

// ADD RELEVANT LINK FOR NEW PROJECT

Home page

By default, the home page for the docs site is the root readme file.

API

TypeDoc is setup, so that any tsdoc comments written in src/*.ts will be added to the documentation site. With the following requirements:

1. Each documented sub-folder to src must have an index.ts which exports the publicized functions.

export { default as identity } from "./identity";

2. You must add that documented sub-folder's index.ts file to the typedoc.json in the docs folder.

{
	"$schema": "https://typedoc.org/schema.json",
	"entryPoints": ["../src/core/index.ts", "../src/utils/index.ts"],
	"tsconfig": "../tsconfig.json",
	"githubPages": true,
	"readme": "none"
}

Images

You can add images to the api with the following markdown:

![image](../../../static/img/docusaurus.png)

Mermaid

You can add mermaid graphs with the following markdown:

Guides

New markdown document guides can be added to the docs/guides sub-folder and will automatically be included in navigation.

Commands

• test - Opens cypress and the local host server.
• test:headless - Runs cypress headlessly.
• lint - Runs Rome linter
• build - Builds the typescript export
• postinstall - Sets up documentation site on first install
• docs - Generates documentation for GitHub actions
• docs:readme - Transfers root readme into the documentation site homepage.
• docs:start - Starts the doc site with live refresh.

GitHub Actions

• deploy-docs.yml will serve the docusaurus site to gh-pages.
• deploy-npm.yml will ensure cypress tests run correctly before allowing commits to master. On a successful commit to master it will also update the npm package.