feat: add contribution docs

This commit is contained in:
ZanzyTHEbar 2023-03-03 18:30:00 +00:00
parent 92e82f344a
commit 903e3c6065
4 changed files with 137 additions and 6 deletions

View File

@ -74,6 +74,8 @@ const theme = {
collapsible: true,
items: [
{ text: "Docs", link: "/development/docs/dev_docs" },
{ text: "Edit Docs", link: "/development/docs/pages" },
{ text: "Standards", link: "/development/docs/standards" },
],
},
{

View File

@ -53,9 +53,3 @@ This is the documentation for the EyeTrackVR Docs site. It is built using [ViteP
- Do not make naming changes to the `vitepress` folder.
- Do not make major changes to the `vitepress` folder structure without proir consultation of team members.
- For Vue componentes, follow the [Vue3 docs](https://vuejs.org/guide/introduction.html).
### Project Specific Documentation
::: tip
COMING SOON
:::

View File

@ -0,0 +1,72 @@
# Pages {.text-[var(--font-accent)]}
This section will cover how to add or edit pages on the docs website.
Please use the `Github Markdown` flavour for your Markdown files.
Please look at other pages to see how they are formatted, and for examples of how to use Markdown.
## Adding a Page
To add a page, you will need to create a new Markdown file in the `vitepress/docs/src/pages` folder. The file name will be the URL of the page. For example, if you create a file called `my_page.md`, the URL will be `https://docs.eyetrackvr.dev//my_page`.
### Sub-directories
You can also create sub-directories in the `vitepress/docs/src/pages` folder. For example, if you create a file called `my_page.md` in a folder called `my_folder`, the URL will be `https://docs.eyetrackvr.dev//my_folder/my_page`.
This is useful for organizing pages into categories.
### Adding a Page to the Sidebar
To add a page to the sidebar, you will need to add the page to the `vitepress/docs/src/custom/theme/index.js` file.
To do this, you will need to add the page to the `sidebar` object.
For example, if you want to add a page called `my_page.md` to the sidebar, you will need to add the following to the `sidebar` object:
```js
{
text: "Getting Started",
collapsible: true,
items: [
{ text: "Introduction", link: "/getting_started/intro" },
{ text: "Things to know before you start", link: "/getting_started/things_to_know" },
{ text: "My Page", link: "/my_folder/my_page" }, // Add this line - subdir then file
],
},
```
::: info Note
The `link` property does not require a file extension. Please do not add it.
:::
### Title Style {.text-[var(--font-accent)]}
The title style is the style of the title that appears at the top of the page.
We like to keep this cohesive, so please use the following style:
```md
# My Page {.text-[var(--font-accent)]}
```
This will give the title a nice orange colour.
The `{}` are required, and the `.text-[#e67e22]` is the colour using `TailWindCSS` classes. You can also use our built in CSS variables `{.text-[var(--font-accent)]}`. You will find these in the `src/styles/theme.css` file. You can change this to any colour you like, but please keep it consistent with the rest of the site.
::: tip Tip
This entire site supports `TailWindCSS` classes. You can find the documentation [here](https://tailwindcss.com/docs).
All classes you wish to add, must be prefaced with a `.` when inside of the `{}`.
When using classes on `HTML` elements, you can use the `class` attribute. For example:
```html
<h1 class="text-[#e67e22]">My Page</h1>
```
:::
## Editing a Page
To edit a page, you will need to edit the Markdown file in the `vitepress/docs/src/pages` folder.

View File

@ -0,0 +1,63 @@
# Standards Guide
Listed here are the standards that are used for the EyeTrackVR project. These standards are used to ensure that the project is consistent and easy to understand.
## Code Standards
### General
It is by design that we use a static-site framework for the documentation site. This is to ensure that the documentation is easy to maintain and extend. This is also to ensure that the documentation is easy to understand.
We have only a few rules for the documentation site:
- All code should be written in English.
- All code should be written in a way that is easy to understand.
- All code should be written in a way that is easy to maintain.
- All code should be written in a way that is easy to extend.
- Our git commit style is to be followed, in english only.
### Git Commit Style
We use the [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) standard for our git commit style. This is to ensure that our git commits are easy to understand and easy to maintain. This is also to ensure that our git commits are easy to extend.
Git commits are used to with the [Semantic Release](https://semantic-release.gitbook.io/semantic-release/) tool to automatically generate the changelog and versioning for the project. As such, it is important that we follow the Conventional Commits standard, with our own rule customizations.
The following is a list of the customizations that we have made to the Conventional Commits standard:
- We use the `BREAKING CHANGE(S)` or `BREAKING` text to indicate a breaking change.
Our git commit style is as follows:
```bash
<type>[optional scope]: <description>
[optional body]
[optional footer(s)]
```
The following is a list of the types that we use:
- `feat`: A new feature.
- `fix`: A bug fix.
- `docs`: Documentation only changes.
- `style`: Changes that do not affect the meaning of the code (white-space, formatting, missing semi-colons, etc).
- `refactor`: A code change that neither fixes a bug nor adds a feature.
- `perf`: A code change that improves performance.
- `test`: Adding missing or correcting existing tests.
- `build`: Changes that affect the build system or external dependencies (example scopes: gulp, broccoli, npm, yarn, actions).
- `ci`: Changes to our CI configuration files and scripts (example scopes: GH-Actions, yml, YAML).
- `chore`: Other changes that don't modify src or test files.
- `revert`: Reverts a previous commit.
- `BREAKING CHANGE`: Indicate a breaking change.
- `no-release`: This commit will not trigger a release.
An example of our git commit style is as follows:
```bash
feat: add a new feature # this is the commit title
- added new thing # some detail about the new thing
BREAKING CHANGE: this is a breaking change #this line is optionaland only used if needed
```