mirror of https://github.com/Qiskit/qiskit.org.git
Docs/nuxt 3 migration (#3103)
* chore: remove unnecessary READMEs * docs: simplify ARCHITECTURE file * docs: update README Also removed unnecessary, trivial or no longer correct information
This commit is contained in:
Eddybrando Vásquez
GitHub
parent
0562e0da53
commit
458758384d
123
ARCHITECTURE.md
123
ARCHITECTURE.md
|
|
@ -2,142 +2,43 @@
|
|||
|
||||
Technical overview of how the code is structured and how it all comes together.
|
||||
|
||||
We try to follow [Nuxt 3](https://nuxt.com/)'s recommendations and best practices. This document only covers the parts that are specific to Qiskit.org.
|
||||
|
||||
## Table of contents
|
||||
|
||||
- [Vue.js components](#vuejs-components)
|
||||
- [Vuex store](#vuex-store)
|
||||
- [Design system](#design-system)
|
||||
- [CSS](#css)
|
||||
- [Markdown content](#markdown-content)
|
||||
- [Testing](#testing)
|
||||
- [Third-party integrations](#third-party-integrations)
|
||||
|
||||
## Vue.js components
|
||||
|
||||
We use components from the [@qiskit-community/qiskit-vue](https://github.com/qiskit-community/qiskit-vue) component library.
|
||||
|
||||
**Note:** We're currently still extracting and migrating reusable components from this project to the component library project.
|
||||
|
||||
Additionally, we write components specific to this project in the `components` directory as [single file components](https://vuejs.org/v2/guide/single-file-components.html).
|
||||
|
||||
The **script section** is written in [class-style syntax](https://class-component.vuejs.org/) with TypeScript and uses decorators provided by [**vue-property-decorator**](https://github.com/kaorun343/vue-property-decorator).
|
||||
|
||||
The **style section** is written in SCSS.
|
||||
|
||||
Here is an example of a component called `CardComponent.vue`:
|
||||
|
||||
```vue
|
||||
<template>
|
||||
<div class="card">
|
||||
<h3 class="card__title" v-text="title" />
|
||||
<p class="card__description" v-text="description" />
|
||||
</div>
|
||||
</template>
|
||||
|
||||
<script lang="ts">
|
||||
import Vue from "vue";
|
||||
import { Component, Prop } from "vue-property-decorator";
|
||||
|
||||
@Component
|
||||
export default class CardComponent extends Vue {
|
||||
@Prop({ type: String, required: true }) title!: string;
|
||||
@Prop({ type: String, required: true }) description!: string;
|
||||
}
|
||||
</script>
|
||||
|
||||
<style lang="scss" scoped>
|
||||
@import "~carbon-components/scss/globals/scss/typography";
|
||||
|
||||
.card {
|
||||
background-color: carbon.$cool-gray-10;
|
||||
|
||||
&__title {
|
||||
@include carbon.type-style("productive-heading-02");
|
||||
}
|
||||
|
||||
&__description {
|
||||
@include carbon.type-style("body-long-01");
|
||||
}
|
||||
}
|
||||
</style>
|
||||
```
|
||||
|
||||
## Vuex store
|
||||
|
||||
We divide our store into [modules](https://vuex.vuejs.org/guide/modules.html).
|
||||
|
||||
To avoid unnecessary boilerplate, we commit _mutations_ directly from Vue.js components and only create _actions_ to dispatch if:
|
||||
|
||||
- we need to commit multiple mutations,
|
||||
- we can reduce complexity by reusing mutations, or
|
||||
- we need to perform asynchronous operations.
|
||||
|
||||
## Design system
|
||||
|
||||
Our design is based on the [Carbon Design System](https://www.carbondesignsystem.com/), which is integrated in `/plugins/carbon.ts`.
|
||||
Our design is based on the [Carbon Design System](https://www.carbondesignsystem.com/).
|
||||
|
||||
## CSS
|
||||
|
||||
We write our CSS in SCSS and employ [BEM's naming convention](https://getbem.com/).
|
||||
|
||||
Global and reusable styles are stored in `assets/scss`.
|
||||
|
||||
- `assets/scss/blocks/copy.scss` defines the typography styles
|
||||
- `assets/scss/layout.scss` contains core layout definitions
|
||||
- `assets/scss/mixins.scss` contains the mixins
|
||||
- `assets/scss/mq.scss` defines the layout breakpoints
|
||||
|
||||
## Markdown content
|
||||
|
||||
We use Markdown files to add content and have two different approaches for this:
|
||||
|
||||
- content (old)
|
||||
- new-content (new)
|
||||
|
||||
These approaches currently coexist but we aim to replace the former with the latter.
|
||||
|
||||
### content (old)
|
||||
|
||||
The old approach takes the Markdown files inside the `content` directory and generates a route for each one, as configured in `nuxt.config.ts` in the [**generate** property](https://nuxtjs.org/docs/2.x/configuration-glossary/configuration-generate/#routes).
|
||||
|
||||
For each route, the content gets extracted from the corresponding Markdown file and the page is generated using `pages/<path>/_slug.vue` as a template.
|
||||
|
||||
To load the Front Matter attributes, we use [frontmatter-markdown-loader](https://github.com/hmsk/frontmatter-markdown-loader).
|
||||
|
||||
### new-content (new)
|
||||
|
||||
The new approach leverages the [**@nuxt/content** module](https://content.nuxtjs.org/), parsing the Markdown files inside the `new-content` directory and making their content fetchable via the `$content` instance.
|
||||
|
||||
## Testing
|
||||
|
||||
We test our codebase with static and unit tests. These are integrated into our CI/CD pipeline, preventing code changes containing non-passing tests to be integrated into our main branch.
|
||||
|
||||
### Static tests
|
||||
|
||||
We use [TypeScript](https://www.typescriptlang.org/) and [ESLint](https://eslint.org/) to validate our JavaScript code.
|
||||
|
||||
### Unit tests
|
||||
|
||||
We write unit tests with Jest to target critical behavior and functionality.
|
||||
|
||||
Changes to one of the following must include new or update existing tests:
|
||||
|
||||
- hooks
|
||||
- plugins
|
||||
- store
|
||||
We test our codebase with Vitest tests. These are integrated into our CI/CD pipeline, preventing code changes containing non-passing tests to be integrated into our main branch.
|
||||
|
||||
## Third-party integrations
|
||||
|
||||
### Airtable
|
||||
|
||||
We fetch content from [Airtable](https://airtable.com/) before the NuxtJS build starts, as configured in the **hooks** property in `nuxt.config.ts`.
|
||||
We fetch content from [Airtable](https://airtable.com/) during our builds for production.
|
||||
|
||||
This content is then stored in JSON files and those files are later fetched via Vuex actions.
|
||||
This content is then stored in JSON files and used to be displayed in the website.
|
||||
|
||||
### Carbon Web Components
|
||||
|
||||
We use web components from the [Carbon Web Components](https://github.com/carbon-design-system/carbon-for-ibm-dotcom) component library.
|
||||
|
||||
### Hotjar
|
||||
|
||||
We use Hotjar for analytics and integrate it by loading the plugin in `/plugins/hotjar.ts`.
|
||||
We use Hotjar for analytics.
|
||||
|
||||
### Segment
|
||||
|
||||
We use [Segment](https://segment.com/) for analytics and integrate it by loading the plugin in `/plugins/segment-analytics` when on production or when we enable analytics via an environment flag, as configured in the **plugins** property in `nuxt.config.ts`.
|
||||
We use [Segment](https://segment.com/) for analytics.
|
||||
|
|
|
|||
134
README.md
134
README.md
|
|
@ -63,11 +63,8 @@ git branch -u upstream/main main
|
|||
- [💻 Technology Used](#-technology-used)
|
||||
- [🚀 Get Up and Running](#-get-up-and-running)
|
||||
- [🏭 Content Generation](#-content-generation)
|
||||
- [🎚️Other environment flags](#️other-environment-flags)
|
||||
- [Enable analytics](#enable-analytics)
|
||||
- [🧐 Directory structure](#-directory-structure)
|
||||
- [✏️ How to Contribute](#️-how-to-contribute)
|
||||
- [🛠 Available Scripts](#-available-scripts)
|
||||
- [🗓 Open backlog](#-open-backlog)
|
||||
- [👩💻 Maintainers](#-maintainers)
|
||||
|
||||
|
|
@ -77,13 +74,9 @@ git branch -u upstream/main main
|
|||
|
||||
## 💻 Technology Used
|
||||
|
||||
Qiskit.org is a pre-rendering SPA using [Nuxt.js](https://nuxtjs.org/).
|
||||
Qiskit.org is a static website generated using [Nuxt](https://nuxt.com/).
|
||||
|
||||
A **pre-rendering SPA** is a single page application that generates a static markup (HTML) at build time. The user, when entering the web, receives HTML (as if it were a static web) but in the meantime, JS files belonging to the SPA are loaded “hydrating” the web until it's completely dynamic.
|
||||
|
||||
**[Nuxt.js](https://nuxtjs.org/)** is the biggest framework on top of **[Vue.js](https://vuejs.org/)** to generate _universal_ SPAs. Universal or "isomorphic" apps can be pre-rendering or SSR. Since so far we don't need server functions, our website is just pre-rendering.
|
||||
|
||||
We create and run unit tests using [Jest](https://jestjs.io/), ensure avoiding syntax errors using [ESLint](https://eslint.org/) and automate all these previous tools and deployment using [GitHub Actions](https://github.com/features/actions).
|
||||
We create and run tests using [Vitest](https://vitest.dev/), ensure avoiding syntax errors using [ESLint](https://eslint.org/) and [Stylelint](https://stylelint.io/), and automate the code integration and deployment using [GitHub Actions](https://github.com/features/actions).
|
||||
|
||||
With this technology we want to **achieve**:
|
||||
|
||||
|
|
@ -129,134 +122,17 @@ Notice that, for communicating with the team tools, API keys may be required. It
|
|||
GENERATE_CONTENT=1 AIRTABLE_API_KEY=<your airtable api key> npm run dev
|
||||
```
|
||||
|
||||
## 🎚️Other environment flags
|
||||
|
||||
### Enable analytics
|
||||
|
||||
In production, the user can authorize us to gather analytics so we can identify
|
||||
trends and improve our user experience. In development, analytics are disabled
|
||||
by default. To enable, set the `ENABLE_ANALYTICS` environment variable.
|
||||
|
||||
## 🧐 Directory structure
|
||||
|
||||
qiskit.org/
|
||||
├─ assets/
|
||||
├─ components/
|
||||
├─ constants/
|
||||
├─ content/
|
||||
├─ deploy/
|
||||
├─ hooks/
|
||||
├─ layouts/
|
||||
├─ mixins/
|
||||
├─ new-content/
|
||||
├─ pages/
|
||||
├─ plugins/
|
||||
├─ static/
|
||||
├─ store/
|
||||
├─ tests/
|
||||
├─ types/
|
||||
├─ nuxt.config.js
|
||||
├─ ... other third-parties configuration files like ESLint, Jest or GitHub Actions
|
||||
|
||||
- **`assets/`**: Un-compiled Sass files.
|
||||
|
||||
More information: [NuxtJS documentation on the _assets_ directory](https://nuxtjs.org/docs/2.x/directory-structure/assets)
|
||||
|
||||
- **`components/`**: Vue.js components.
|
||||
|
||||
More information: [NuxtJS documentation on the _components_ directory](https://nuxtjs.org/docs/2.x/directory-structure/components)
|
||||
|
||||
- **`constants/`**: Shared constants.
|
||||
|
||||
- **`content/`**: Content Markdown and JSON files included via the [`generate` property](https://nuxtjs.org/docs/2.x/configuration-glossary/configuration-generate/#routes).
|
||||
|
||||
The files are organized in folders matching the website's information architecture.
|
||||
|
||||
- **`deploy/`**: Deployment configuration.
|
||||
|
||||
- **`hooks/`**: Shared hook functions.
|
||||
|
||||
- **`layouts/`**: Nuxt layout components.
|
||||
|
||||
More information: [NuxtJS documentation on the _layouts_ directory](https://nuxtjs.org/docs/2.x/directory-structure/layouts)
|
||||
|
||||
- **`mixins/`**: Shared Vue.js mixins.
|
||||
|
||||
- **`new-content/`**: Content Markdown files included via `@nuxtjs/content`.
|
||||
|
||||
This directory would usually be named `content`, but that name was already in use in our project.
|
||||
|
||||
More information: [NuxtJS documentation on the _content_ directory](https://nuxtjs.org/docs/2.x/directory-structure/content)
|
||||
|
||||
- **`pages/`**: The base application views and routes.
|
||||
|
||||
More information: [NuxtJS documentation on the _pages_ directory](https://nuxtjs.org/docs/2.x/directory-structure/pages)
|
||||
|
||||
- **`plugins/`**: JavaScript plugins that run before instantiating the root Vue.js application.
|
||||
|
||||
More information: [NuxtJS documentation on the _pages_ directory](https://nuxtjs.org/docs/2.x/directory-structure/plugins)
|
||||
|
||||
- **`static/`**: Files that will be automatically served by Nuxt and will be accessible through the project root URL.
|
||||
|
||||
More information: [NuxtJS documentation on the _static_ directory](https://nuxtjs.org/docs/2.x/directory-structure/static)
|
||||
|
||||
- **`store/`**: Vuex store files.
|
||||
|
||||
More information: [NuxtJS documentation on the _store_ directory](https://nuxtjs.org/docs/2.x/directory-structure/store)
|
||||
|
||||
- **`tests/`**: Jest unit tests.
|
||||
|
||||
- **`types/`**: Additional types for non-typed libraries or global definitions.
|
||||
|
||||
- **`nuxt.config.js`**: Main NuxtJS configuration.
|
||||
|
||||
More information: [NuxtJS documentation on the _nuxt.config_ file](https://nuxtjs.org/docs/2.x/directory-structure/nuxt-config)
|
||||
We follow Nuxt's [directory structure](https://nuxt.com/docs/guide/directory-structure/nuxt).
|
||||
|
||||
## ✏️ How to Contribute
|
||||
|
||||
Contributions are always welcome, no matter how large or small. Before contributing, please read the [contributing guide](CONTRIBUTING.md) and [code of conduct](CODE_OF_CONDUCT.md).
|
||||
|
||||
## 🛠 Available Scripts
|
||||
|
||||
Run a local server enabling inspector agent:
|
||||
|
||||
```shell
|
||||
npm run dev-debug
|
||||
```
|
||||
|
||||
Run unit tests made with [Jest](https://jestjs.io/):
|
||||
|
||||
```shell
|
||||
npm run test
|
||||
```
|
||||
|
||||
Build static version ready for production, output will be generated inside a new folder called `dist`:
|
||||
|
||||
```shell
|
||||
npm run build
|
||||
```
|
||||
|
||||
Run a local server on the website's production built. Make sure you ran `npm run build` first:
|
||||
|
||||
```shell
|
||||
npm run start
|
||||
```
|
||||
|
||||
Find syntax errors. We use [ESLint](https://eslint.org/):
|
||||
|
||||
```shell
|
||||
npm run lint
|
||||
```
|
||||
|
||||
Autofix linter:
|
||||
|
||||
```shell
|
||||
npm run fix-lint
|
||||
```
|
||||
Contributions are always welcomed, no matter how large or small. Before contributing, please read the [contributing guide](CONTRIBUTING.md) and [code of conduct](CODE_OF_CONDUCT.md).
|
||||
|
||||
## 🗓 Open backlog
|
||||
|
||||
You can see our backlog [here](https://github.com/Qiskit/qiskit.org/projects/2).
|
||||
You can see our backlog [here](https://github.com/orgs/Qiskit/projects/10).
|
||||
|
||||
## 👩💻 Maintainers
|
||||
|
||||
|
|
|
|||
|
|
@ -1,15 +0,0 @@
|
|||
# COMPONENTS
|
||||
|
||||
The components directory contains the Vue.js Components. We are working with the following structure to organize our components:
|
||||
|
||||
- 📁 **ui/** : Generic components like button, carousel, list, ... not related to an specific domain that can be reusable across the whole app
|
||||
- 📁 **layout/** : Components that are used in the nuxt `layouts` folder (Header, Footer, ...). They are part of all pages.
|
||||
- 📁 **logic/** : Components that only has logic inside, not `<template>` block
|
||||
- 📁 **[domain]/** : Components that belong to a specific domain. The folder name should be the "domain" it refers to, having one folder per domain. For example, an AdvocateCard is related to the advocates domain, even if it is used in more than one place. If we have a generic `card` that can be used for both `advocates` and `events` (for example) it should go to ui. At the moment, we have the following domains:
|
||||
- 📁 **advocates/**
|
||||
- 📁 **events/**
|
||||
|
||||
You should also have in mind this guidelines:
|
||||
|
||||
- If your component is compound of more subcomponents, make a folder called like the component (like with `ui/footer`).
|
||||
- If you add a component similar to another one, consider creating a folder with the naming the collection of components (as in `ui/sections`).
|
||||
|
|
@ -1,9 +0,0 @@
|
|||
# Events content
|
||||
|
||||
This directory contains the events content data.
|
||||
|
||||
## JSON files
|
||||
|
||||
The JSON files are automatically generated by a script that fetches their content from an external database.
|
||||
|
||||
They are included in version control to simplify running and testing the project locally, but they shouldn't be modified.
|
||||
Loading…
Reference in New Issue