Skip to content

Latest commit

 

History

History
86 lines (53 loc) · 3.7 KB

running_tasks.md

File metadata and controls

86 lines (53 loc) · 3.7 KB
Raw

Build Tasks

The narrative repo has a number of npm and grunt tasks configured for developer use and convenience. They can be found in the scripts section of the package.json file and Gruntfile.js.

Updating your npm packages

If you haven't already done so, run

npm install

to install and update the npm packages required by the narrative. If there are errors, you may need to remove the package-lock.json file and/or the node_modules directory.

Building style files

KBase serves concatenated, minified css files (generally named *_concat.css) to minimise download size and HTTP hits. These are produced from the scss source files in kbase-extension/scss by an npm script which triggers the sass compiler and then runs Autoprefixer on the output.

To update the css files, run the task:

npm run compile_css

If this is not run, edits to the scss source files will not be reflected in the css file served by the browser.

There is also a watch task that will automatically generate the concatenated, minified css files when there is a change to the source files. If you plan to make changes to frontend styling, run

grunt watch

in a terminal window to launch a watcher process that regenerates the css files when changes are made. It is recommended that you have this running in a terminal window when running the kbase-narrative script in another window.

Style file styling

The narrative repo uses the PostCSS system for post-processing css; this includes minification and Autoprefixer for adding browser prefixes. SCSS linting is provided by Stylelint.

Additions to the source files should be written without vendor prefixes as these will be added automatically.

Autoprefixer

The narrative repo uses Autoprefixer to add browser prefixes to css, with the browser support list set to Autoprefixer's default setting. The update_browserslist npm script is used by Autoprefixer to pull in the latest browser configurations, and is run as a git hook. If running the script returns a message that the list of browsers has been updated, please commit the updated package-lock.json file.

For more information, see the browserslist best practices and updating sections.

Stylelint

To lint the scss files, run the command

npm run stylelint

The linter config (in .stylelint.yaml) includes a number of rules to ensure that the scss content is error-free and (relatively) uniform. Running it will automatically fix some stylistic issues (e.g. ordering of lines within stanzas), but others may need to be fixed manually. Please note there are some issues in the SCSS files that are more difficult to fix, due to the styling set in the Jupyter notebook css.

JavaScript formatting and linting

The narrative repo uses [Prettier][https://github.com/prettier/prettier] for code formatting and [ESLint][https://eslint.org] for code linting. Developers can use the aliases in the package.json file to run these tools:

npm run eslint   # runs eslint over the JS codebase
npm run prettier # formats JS files

Python formatting and linting

The narrative repo installation includes [Ruff][https://docs.astral.sh/ruff/], a code formatter and linter, for code QA. You can run these commands manually using the aliases set up in the package.json file:

$ npm run py-format  # autoformats python code
$ npm run py-lint  # runs code linter

or trigger them directly from the command line, e.g.

$ ruff format .
$ ruff check --autofix .