Uses Gatsby to build static site.
Snooty uses artifactory that will need authentication to install some private npm packages. Update your local zsh variables in $~/.zshrc (in Windows %USERPROFILE%/.zshrc) to include the following
export NPM_BASE_64_AUTH=<BASE_64_API_KEY>
export NPM_EMAIL=<your.email@gmail.com>
Then, to install the package dependencies:
npm install --legacy-peer-depsYou'll need to set some environment variables in two separate files at the root of this directory for separate production/development environments. These variables let Snooty know where to look for your AST zip files, within DOP team's database. (You can also use local AST files))
Snooty's develop stage uses the development environment. Your .env.development file should be as follows:
GATSBY_SITE=<SITE>
GATSBY_PARSER_USER=<USER>
GATSBY_PARSER_BRANCH=<BRANCH>
GATSBY_SNOOTY_DEV=true
The GATSBY_SNOOTY_DEV variable is what allows Gatsby to know that it should use the snooty branch name as part of the file paths. When not set, the file paths will use the value of GATSBY_PARSER_BRANCH. See pathing here
It should be set to true when working on snooty locally.
Snooty's build and serve stages use the production environment. Your .env.production file should be as follows:
GATSBY_SITE=<SITE>
GATSBY_PARSER_USER=<USER>
GATSBY_PARSER_BRANCH=<BRANCH>
GATSBY_SNOOTY_DEV=true
npm run developTo build and serve the site, run the following commands:
The serve command generates the site at a prefix ie. localhost:9000/<branch>/<docs-name>/<user>/<branch-name>/
$ npm run build
$ npm run serveTo debug server side:
node --nolazy node_modules/.bin/gatsby develop --inspect-brkand connect a node debugger (ie. chrome developer tools)
Alternative to working with remote AST files, you can have a local zip file to build the site. This removes the need for previously mentioned env variables required for remote lookup GATSBY_SITE GATSBY_PARSER_USER and GATSBY_PARSER_BRANCH. Local zip file is an output of the parser
.env.development and .env.production:
GATSBY_MANIFEST_PATH=/path/to/zipped/ast/file.zip
GATSBY_SNOOTY_DEV=true
Install libxml2 with brew install libxml2 on mac and apt-get install libxml2 on linux
Install mut and ensure that you have properly configured your Giza/AWS keys as defined here. Then, from root, run:
npm run build:clean:stagenpm run build before make stage.
We have configured an automatic release process using GitHub Actions that is triggered by npm-version. To release a version, you must have admin privileges in this repo. Then proceed as follows:
- On the
masterbranch, rungit pullfollowed bynpm ci. - Run
npm version [major | minor | patch], using Semantic Versioning guidelines to correctly increment the version number. Keep the minor version consistent with snooty-parser versioning. GitHub Actions will create a new git tag and push it to GitHub. - Update the release draft found here using the automatically generated CHANGELOG.md and publish the release. Keep "pre-release" checked until version 1.0.0.
origin points to a fork.
Tests can be run using:
npm test # alias for npm run testUnit tests are located in the tests/unit/ directory. To run only unit tests, use:
npm run test:unitJest includes configurations for running individual test suites:
npm test -- my-test # or
npm test -- path/to/my-test.jsFor more information, see the Jest CLI Options documentation, or run npm test -- --help.
Snapshots may require updates when making changes to snooty components
npm test -- -uWe use ESLint and Prettier to help with linting and style.
Our CI (via GitHub Actions) is configured to test for lint errors. To run this test locally and attempt to automatically fix errors:
npm run lint:fixThese errors must be fixed for the CI build to pass.
To format code using Prettier, run the following command:
npm run format:fixWe have set up a precommit hook that will format staged files. Prettier also offers a variety of editor integrations to automatically format your code.