Skip to content

pupil-labs/pupil-docs

Folders and files

NameName
Last commit message
Last commit date

Latest commit

0f2cba5 · Sep 5, 2023
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

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

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

Adding new notebooks

The first cell should be a Markdown cell and start with "frontmatter"

---
description: DESCRIPTION
is_notebook: true
---

Directory Structure

.
├── 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
---

Preview social media share

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

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"/>

Videos

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">