Pupil Docs

Pupil Docs website built with Vuepress.

User and Developer Docs for Pupil.

View the docs at docs.pupil-labs.com

Contributing

We welcome all contributions! To edit content:

1. Fork this repository
2. Install dependencies
3. Edit content
4. Test local changes
5. Commit and push to your fork
6. Make a Pull Request

Download

For this project we use Yarn for dependency management.

Download and install Yarn.

Install

Fork or clone this repository and run the following command to install the dependencies.

yarn

Development

Start local development with:

yarn dev

To generate static assets, run:

yarn build

Directory Struture

.
├── src
│   ├── .vuepress
│   │   ├── components
│   │   ├── theme
│   │   │   └── layouts
│   │   ├── public (static)
│   │   │   └── imgs/videos
│   │   ├── config.js
│   │   └── enhanceApp.js
│   │
│   ├── media (processed by webpack)
│   │   └── imgs/videos
│   │
│   ├── core
│   │   ├── user-guide.md
│   │   └── README.md
│   │
│   └── README.md
│
└── package.json

Page routing

In the root dir are where all the page routes are located.

Relative Path	Page Routing
/README.md	/
/core/README.md	/core/

For pages that are not README.md, please add frontmatter with a permalink. This enables us to have "clean" URLs without .html and makes linking within docs easier. Example for /core/software/pupil-capture.md - add the below front-matter:

---
permalink: /core/software/pupil-capture
---

Images & media

• src/media - This is where most people will be adding images, videos, etc. For all assets that will be used in .md files.
• src/.vuepress/public - Primarily for those who are developing the theme. For assets that are used in .vue files.

Relative URLs

All Markdown files are compiled into Vue components and processed by webpack, so you can and should prefer referencing any asset using relative URLs:

![An image](./image.png)

Public files

Sometimes you may need to provide static assets that are not directly referenced in any of your Markdown or theme components - for example, favicons and PWA icons. In such cases, you can put them inside src/.vuepress/public and they will be copied to the root of the generated directory.

Asset formats

• Raster graphics should be and .jpg.
• Vector graphics should be .svg.
• Videos/animations should be .mp4 versions.
• Including image posters as .jpg versions.

Note - webm and webp will be implemented in future iterations.

Style Guide

We aim for the docs to be concise and readable.

All content is written in Markdown. If you're new to Markdown see this guide. HTML markup is also parsed, but discouraged unless absolutely needed.

Table of contents

All H1, H2, H3 headers will be automatically added to the table of contents.

Please only use H1-H4 headings. If you find yourself needing more nesting, you should re-think your content. Don't use H5.

Code blocks

VuePress uses Prism to highlight language syntax in Markdown code blocks, using coloured text. Prism supports a wide variety of programming languages. All you need to do is append a valid language alias to the beginning backticks for the code block:

```python
print("welcome to pupil docs")
```

Custom container

You can add highlighted notes with a little HTML embedded in your markdown document:

Text only

::: tip
Text.
:::

Text with title

::: warning Title
Text.
:::

Text with icon

v-icon is a vuetify tag, so you could change the color property and also replace the icon by changing the error_outline to any Material Icons.

::: danger
<v-icon large color="warning">error_outline</v-icon>
Text.
:::

Youtube videos

Use Youtube component to quickly add videos to markdown files.

Just copy and paste the unique video ID to the src prop of the component like so.

https://www.youtube.com/watch?v=HGMjJLnK2_4

<Youtube src="HGMjJLnK2_4"/>