README.rst

www.lsst.io

https://www.lsst.io is a portal for Rubin Observatory technical documentation. It's designed to help Rubin Observatory staff and the astronomy community discover documentation, software, and other bits of technical information produced by the Rubin Observatory and LSST.

Technical stack

• This site is built with Gatsby and React.
• The search experience is powered by Algolia and react-instantsearch
• Styling is done through styled-components.
• It's deployed on LSST the Docs.
• Searchable content is curated and ingested by Ook, the Rubin Observatory librarian service. Ook ingests URLs/documents on-demand through a Kafka message queue on Roundtable.

Development workflow primer

Node version

The Node.js version used This project is intended to be built with a Node.js version that's encoded in the .nvmrc file. To adopt this node version, we recommend installing and using the node version manager.

Then you can use the preferred node version by running nvm from the project root:

nvm use

Install locally

Install the JavaScript packages:

npm install .

Start the development server

gatsby develop

View the site at http://localhost:8000.

Also view the GraphiQL playground at http://localhost:8000/___graphql to explore the site's data layer.

Install pre-commit hooks

You can automatically lint and format code using pre-commit hooks.

First, install pre-commit in an isolated virtual environment:

python3 -m venv .venv
source .venv/bin/activate
python -m pip install pre-commit
pre-commit install

After this initialization step, you can re-activate the hooks in the virtual environment:

source .venv/bin/activate

Manual linting and formatting

You can also manually lint and format code.

Lint JavaScript:

npm run lint

Lint and auto-format JavaScript (powered by Prettier):

npm run lint:fix

Format other types of code with Prettier:

npm run format

Create a production build

gatsby build

This build static HTML and optimized per-route JavaScript code bundles.

You can serve the production build locally:

gatsby serve

Project layout

Here are the important files and directories:

licenses/

This directory contains licenses for third-party code that is vendored by this project (such as the license for the Gatsby starter files).

node_modules/

This directory contains npm packages, as defined by package.json / package-lock.json. This directory isn't maintained in Git.

src/

This directory contains all the front-end code for www.lsst.io itself.

.pre-commit-config.yaml

Pre-commit hooks that ensure code is correctly formatting and doesn't have any linting issues.

.prettierrc

This file configures Prettier, which automatically formats the codebase.

.prettierignore

This file lists files and directories that Prettier will not format.

gatsby-browser.js

This file is where we extend or customize Gatsby's default settings affecting the browser, through the Gatsby browser APIs.

gatsby-config.js

This is the main Gatsby configuration file. See the Gatsby config docs for details.

gatsby-node.js

This file is where we customize the build process using Gatsby Node APIs.

gatsby-ssr.js

This file is where we customize Gatsby's server-side rendering with the Gatsby SSR APIs.

LICENSE

This project is licensed under MIT, along with the sub-licenses listed in licenses/.

package-lock.json

A file is generated based on package.json and contains the exact version of npm dependencies.

pacakge.json

This file is the manifest for the Node.js project and contains the project's metadata and abstract dependencies.