Pupil Docs website built with Vuepress.
User and Developer Docs for Pupil.
View the docs at docs.pupil-labs.com
We welcome all contributions! To edit content:
- Fork this repository
- Install dependencies
- Edit content
- Test local changes
- Commit and push to your fork
- Make a Pull Request
For this project, we use Yarn for dependency management.
Download and install Yarn.
Fork or clone this repository and run the following command to install the dependencies.
yarn
To generate markdown files from Jupyter notebooks install nbconvert via
pip install nbconvert
and run the following command
jupyter-nbconvert --to markdown **/*.ipynb --ExtractOutputPreprocessor.enabled=False
on a Windows machine, you can achieve the same output by running the following command using PowerShell
ls *.ipynb -Recurse | foreach{jupyter-nbconvert --to markdown $_ --ExtractOutputPreprocessor.enabled=False}
Start local development with:
yarn dev
To generate static assets, run:
yarn build
The first cell should be a Markdown cell and start with "frontmatter"
---
description: DESCRIPTION
is_notebook: true
---
.
├── 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
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
---
The social media preview is generated by Vuepress via frontmatter of each .md
file. Anyone working on docs can just update the frontmatter to update the preview.
This is an example frontmatter config for showing a preview image, using Twitter (X) Summary Card. You can also use Youtube thumbnail URL for the preview image. A valid URL is required to show a preview image.
---
title: Title of the current page.
description: Description of the current page.
permalink: /<url>
meta:
- name: twitter:card
content: summary_large_image
- name: twitter:image
content: "https://i.ytimg.com/vi/cuvWqVOAc5M/maxresdefault.jpg"
- property: og:image
content: "https://i.ytimg.com/vi/cuvWqVOAc5M/maxresdefault.jpg"
tags: [Neon]
---
If you would like to preview Youtube video, you can use Twitter (X) Player Card and update the meta config like so:
Just update the Youtube video id in the example
meta:
- name: twitter:card
content: player
- name: twitter:image
content: "https://i.ytimg.com/vi/cuvWqVOAc5M/maxresdefault.jpg"
- name: twitter:player
content: "https://www.youtube.com/embed/cuvWqVOAc5M"
- name: twitter:width
content: "1280"
- name: twitter:height
content: "720"
- property: og:image
content: "https://i.ytimg.com/vi/cuvWqVOAc5M/maxresdefault.jpg"
Read more: https://vuepress.vuejs.org/guide/frontmatter.html#alternative-frontmatter-formats
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.
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)
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.
- 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.
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.
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.
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")
```
You can add highlighted notes with a little HTML embedded in your markdown document:
::: tip
Text.
:::
::: warning Title
Text.
:::
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.
:::
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"/>
Use Videos component to quickly add local videos to markdown files.
Just add the relative path of the video to the src prop of the component like so.
Note that you need to use require
in order for Webpack to correctly resolve the path.
<Videos :src="require(`../../media/core/videos/worldcam-focus.mp4`)">
The default video type is video/mp4
which is automatically added but in case you are using a different type of video, just update the type prop.
<Videos :src="require(`../../media/core/videos/worldcam-focus.webm`)" type="video/webm">