Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Docusaurus docs #1397

Draft
wants to merge 12 commits into
base: master
Choose a base branch
from
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
35 changes: 12 additions & 23 deletions .readthedocs.yaml
Original file line number Diff line number Diff line change
@@ -1,28 +1,17 @@
version: 2

sphinx:
builder: html
configuration: docs/source/conf.py
fail_on_warning: true

build:
os: ubuntu-22.04
tools:
python: "3.11"
jobs:
post_checkout:
# Cancel building pull requests when there aren't changed in the docs directory or YAML file.
# You can add any other files or directories that you'd like here as well,
# like your docs requirements file, or other files that will change your docs build.
#
# If there are no changes (git diff exits with 0) we force the command to return with 183.
# This is a special exit code on Read the Docs that will cancel the build immediately.
- |
if [ "$READTHEDOCS_VERSION_TYPE" = "external" ] && git diff --quiet origin/master -- docs/ .readthedocs.yaml;
then
exit 183;
fi

python:
install:
- requirements: docs/requirements.txt
nodejs: "18"
commands:
# "docs/" directory was created using the command to create the site:
# npx create-docusaurus@latest docs classic
#
# Install Docusaurus dependencies
- cd docs/ && npm install
# Build the site
- cd docs/ && npm run build
# Copy generated files into Read the Docs directory
- mkdir --parents _readthedocs/html/
- cp --recursive docs/build/* _readthedocs/html/
9 changes: 9 additions & 0 deletions docs-old/.gitignore
Original file line number Diff line number Diff line change
@@ -0,0 +1,9 @@
build/*
.DS_Store
.vscode/*
.idea/*
source/_build
source/docs/_build

venv/*
.venv/*
File renamed without changes.
File renamed without changes.
File renamed without changes.
9 changes: 9 additions & 0 deletions docs-old/README.MD
Original file line number Diff line number Diff line change
@@ -0,0 +1,9 @@
# PhotonVision ReadTheDocs

[![Documentation Status](https://readthedocs.org/projects/photonvision-docs/badge/?version=latest)](https://docs.photonvision.org/en/latest/?badge=latest)

PhotonVision is a free open-source vision processing software for FRC teams.

This repository is the source code for our ReadTheDocs documentation, which can be found [here](https://docs.photonvision.org).

[Contribution and formatting guidelines for this project](https://docs.photonvision.org/en/latest/docs/contributing/photonvision-docs/index.html)
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
25 changes: 18 additions & 7 deletions docs/.gitignore
Original file line number Diff line number Diff line change
@@ -1,9 +1,20 @@
build/*
# Dependencies
/node_modules

# Production
/build

# Generated files
.docusaurus
.cache-loader

# Misc
.DS_Store
.vscode/*
.idea/*
source/_build
source/docs/_build
.env.local
.env.development.local
.env.test.local
.env.production.local

venv/*
.venv/*
npm-debug.log*
yarn-debug.log*
yarn-error.log*
42 changes: 37 additions & 5 deletions docs/README.MD
Original file line number Diff line number Diff line change
@@ -1,9 +1,41 @@
# PhotonVision ReadTheDocs
# Website

[![Documentation Status](https://readthedocs.org/projects/photonvision-docs/badge/?version=latest)](https://docs.photonvision.org/en/latest/?badge=latest)
This website is built using [Docusaurus](https://docusaurus.io/), a modern static website generator.

PhotonVision is a free open-source vision processing software for FRC teams.
### Installation

This repository is the source code for our ReadTheDocs documentation, which can be found [here](https://docs.photonvision.org).
```
$ yarn
```

[Contribution and formatting guidelines for this project](https://docs.photonvision.org/en/latest/docs/contributing/photonvision-docs/index.html)
### Local Development

```
$ yarn start
```

This command starts a local development server and opens up a browser window. Most changes are reflected live without having to restart the server.

### Build

```
$ yarn build
```

This command generates static content into the `build` directory and can be served using any static contents hosting service.

### Deployment

Using SSH:

```
$ USE_SSH=true yarn deploy
```

Not using SSH:

```
$ GIT_USER=<Your GitHub username> yarn deploy
```

If you are using GitHub pages for hosting, this command is a convenient way to build the website and push to the `gh-pages` branch.
3 changes: 3 additions & 0 deletions docs/babel.config.js
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
module.exports = {
presets: [require.resolve('@docusaurus/core/lib/babel/preset')],
};
12 changes: 12 additions & 0 deletions docs/blog/2019-05-28-first-blog-post.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,12 @@
---
slug: first-blog-post
title: First Blog Post
authors: [slorber, yangshun]
tags: [hola, docusaurus]
---

Lorem ipsum dolor sit amet...

<!-- truncate -->

...consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet
44 changes: 44 additions & 0 deletions docs/blog/2019-05-29-long-blog-post.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,44 @@
---
slug: long-blog-post
title: Long Blog Post
authors: yangshun
tags: [hello, docusaurus]
---

This is the summary of a very long blog post,

Use a `<!--` `truncate` `-->` comment to limit blog post size in the list view.

<!-- truncate -->

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet
24 changes: 24 additions & 0 deletions docs/blog/2021-08-01-mdx-blog-post.mdx
Original file line number Diff line number Diff line change
@@ -0,0 +1,24 @@
---
slug: mdx-blog-post
title: MDX Blog Post
authors: [slorber]
tags: [docusaurus]
---

Blog posts support [Docusaurus Markdown features](https://docusaurus.io/docs/markdown-features), such as [MDX](https://mdxjs.com/).

:::tip

Use the power of React to create interactive blog posts.

:::

{/* truncate */}

For example, use JSX to create an interactive button:

```js
<button onClick={() => alert('button clicked!')}>Click me!</button>
```

<button onClick={() => alert('button clicked!')}>Click me!</button>
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
29 changes: 29 additions & 0 deletions docs/blog/2021-08-26-welcome/index.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,29 @@
---
slug: welcome
title: Welcome
authors: [slorber, yangshun]
tags: [facebook, hello, docusaurus]
---

[Docusaurus blogging features](https://docusaurus.io/docs/blog) are powered by the [blog plugin](https://docusaurus.io/docs/api/plugins/@docusaurus/plugin-content-blog).

Here are a few tips you might find useful.

<!-- truncate -->

Simply add Markdown files (or folders) to the `blog` directory.

Regular blog authors can be added to `authors.yml`.

The blog post date can be extracted from filenames, such as:

- `2019-05-30-welcome.md`
- `2019-05-30-welcome/index.md`

A blog post folder can be convenient to co-locate blog post images:

![Docusaurus Plushie](./docusaurus-plushie-banner.jpeg)

The blog supports tags as well!

**And if you don't want a blog**: just delete this directory, and use `blog: false` in your Docusaurus config.
23 changes: 23 additions & 0 deletions docs/blog/authors.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,23 @@
yangshun:
name: Yangshun Tay
title: Front End Engineer @ Facebook
url: https://github.com/yangshun
image_url: https://github.com/yangshun.png
page: true
socials:
x: yangshunz
github: yangshun

slorber:
name: Sébastien Lorber
title: Docusaurus maintainer
url: https://sebastienlorber.com
image_url: https://github.com/slorber.png
page:
# customize the url of the author page at /blog/authors/<permalink>
permalink: '/all-sebastien-lorber-articles'
socials:
x: sebastienlorber
linkedin: sebastienlorber
github: slorber
newsletter: https://thisweekinreact.com
19 changes: 19 additions & 0 deletions docs/blog/tags.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,19 @@
facebook:
label: Facebook
permalink: /facebook
description: Facebook tag description

hello:
label: Hello
permalink: /hello
description: Hello tag description

docusaurus:
label: Docusaurus
permalink: /docusaurus
description: Docusaurus tag description

hola:
label: Hola
permalink: /hola
description: Hola tag description
46 changes: 46 additions & 0 deletions docs/docs/additional-resources/config.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,46 @@
# Filesystem Directory

PhotonVision stores and loads settings in the `photonvision_config` directory, in the same folder as the PhotonVision JAR is stored. On the Pi image as well as the Gloworm, this is in the `/opt/photonvision` directory. The contents of this directory can be exported as a zip archive from the settings page of the interface, under "export settings". This export will contain everything detailed below. These settings can later be uploaded using "import settings", to restore configurations from previous backups.

## Directory Structure

The directory structure is outlined below.

<img src={require('./images/configDir.png').default} alt="Config directory structure" width="600"/>


- calibImgs
- Images saved from the last run of the calibration routine
- cameras
- Contains a subfolder for each camera. This folder contains the following files:
- pipelines folder, which contains a `json` file for each user-created pipeline.
- config.json, which contains all camera-specific configuration. This includes FOV, pitch, current pipeline index, and calibration data
- drivermode.json, which contains settings for the driver mode pipeline
- imgSaves
- Contains images saved with the input/output save commands.
- logs
- Contains timestamped logs in the format `photonvision-YYYY-MM-D_HH-MM-SS.log`. Note that on Pi or Gloworm these timestamps will likely be significantly behind the real time.
- hardwareSettings.json
- Contains hardware settings. Currently this includes only the LED brightness.
- networkSettings.json
- Contains network settings, including team number (or remote network tables address), static/dynamic settings, and hostname.

## Importing and Exporting Settings

The entire settings directory can be exported as a ZIP archive from the settings page.

<video width="85%" controls>
<source src={require("@site/docs/assets/import-export-settings.mp4").default} type="video/mp4"></source>
Your browser does not support the video tag.
</video>

A variety of files can be imported back into PhotonVision:

- ZIP Archive (`.zip`)
- Useful for restoring a full configuration from a different PhotonVision instance.
- Single Config File
- Currently-supported Files
- `hardwareConfig.json`
- `hardwareSettings.json`
- `networkSettings.json`
- Useful for simple hardware or network configuration tasks without overwriting all settings.
Original file line number Diff line number Diff line change
Expand Up @@ -2,13 +2,13 @@

## About

:::{warning}
:::warning
PhotonVision interfaces with PhotonLib, our vendor dependency, using NetworkTables. If you are running PhotonVision on a robot (ie. with a RoboRIO), you should **turn the NetworkTables server switch (in the settings tab) off** in order to get PhotonLib to work. Also ensure that you set your team number. The NetworkTables server should only be enabled if you know what you're doing!
:::

## API

:::{warning}
:::warning
NetworkTables is not a supported setup/viable option when using PhotonVision as we only send one target at a time (this is problematic when using AprilTags, which will return data from multiple tags at once). We recommend using PhotonLib.
:::

Expand Down Expand Up @@ -51,7 +51,7 @@ Images are returned as part of the .zip package from the "Export" operation in t
| `inputSaveImgCmd` | `boolean` | Triggers saving the current input image to file. |
| `outputSaveImgCmd` | `boolean` | Triggers saving the current output image to file. |

:::{warning}
:::warning
If you manage to make calls to these commands faster than 500ms (between calls), additional photos will not be captured.
:::

Expand All @@ -63,8 +63,8 @@ These entries are global, meaning that they should be called on the main `photon
| --------- | ----- | -------------------------------------------------------- |
| `ledMode` | `int` | Sets the LED Mode (-1: default, 0: off, 1: on, 2: blink) |

:::{warning}
Setting the LED mode to -1 (default) when `multiple` cameras are connected may result in unexpected behavior. {ref}`This is a known limitation of PhotonVision. <docs/troubleshooting/common-errors:LED Control>`
:::warning
Setting the LED mode to -1 (default) when `multiple` cameras are connected may result in unexpected behavior. \{ref}`This is a known limitation of PhotonVision. <docs/troubleshooting/common-errors:LED Control>`

Single camera operation should work without issue.
:::
Loading
Loading