Beta Version of the Voxel51 Technical Documentation

This is the source repository for the Voxel51 documentation site - https://beta-docs.voxel51.com

We love pull requests - everything from typos to full Jupyter Notebooks.

At its most simple, you can fork the repo in GitHub, make and commit your edits, and then open a PR. A step above would be setting up local development.

Editing the markdown documentation (under /docs)

To install and edit the general docs doc:

1. Make and activate a virtual environment, we recommend you to use Python 3.11 for this.

   # Create a virtual environment named '.venv'
   python3 -m venv .venv
   
   # Activate the virtual environment
   source .venv/bin/activate
   
   # On linux/mac/Windows WSL
   source .venv\bin\activate
   
   # On windows in Powershell
   source .venv\Scripts\activate`

2. Be in the root directory of the repo and install the dependencies

   pip install -r requirements.txt

3. Serve the docs

   mkdocs serve --dirty

   The --dirty flag specifies that if you edit a single file, mkdocs serve will only rebuild that one file rather than the entire documentation site. To do a clean build and force mkdocs to build everything run

   mkdocs serve

   Clean is the default behavior.

4. PARTY!

If you find errors while executing mkdocs serve related to the docs/api and docs/ts_api folders delete their symlinks and rerun the command.

Building the Entire Site

To build the entire doc site (only been tested on Linux). This is required if you want to see the true rendering of the Jupyter notebooks. The current plugin does not respect paths for external files so there is a Python script, jupyter-image-embed.py to base64 encode the notebook's images and then store them directly in the notebook.

That script has a list at the top for all the places to find notebooks. It currently has

1. tutorials
2. recipes
3. getting started

If you want to start to render notebooks in other locations you will need to add it to the list

1. Follow steps 1&2 above
2. ./build.sh --venv <location of the venv you created in step 1 above>
   1. The script will first clone the fiftyone repo, then build the API docs, then encode and embed images in jupyter notebooks, and finally will build the entire site
   2. You will see a lot of log output with some warnings. Those are expected, ignore for now
3. The built site will now be in a directory named "site". This directory is a sister directory to the docs directory
4. To get the site to render properly you need to open it in a web server. Most IDEs have a built in web server that will allow you to serve up the directory as a web site.
   1. VSCode has Live Preview - https://marketplace.visualstudio.com/items?itemName=ms-vscode.live-server
   2. Jetbrains products has a live preview as well - https://www.jetbrains.com/help/idea/editing-html-files.html
   3. If you already have python on your machine, at the terminal, change into the site directory and execute the following command python3 -m http.server. This will spin up a simple web server.
5. Celebration!

The build script accepts the following options:

Options:
    -h, --help             Show this help message
    -v, --verbose          Enable verbose output
    --skip-clone           Skip repository cloning
    --skip-python-api      Skip Python API documentation build
    --skip-ts-api          Skip TypeScript API documentation build
    --skip-all-api         Skip all API documentation builds though this will not prevent the clone
    --version VERSION      Specify the FiftyOne version number to place in the pydoc (default: 1.3)
    --venv VENV_ACTIVATE   Specify the path to your venv's activate script (default: \$HOME/virtualenvs/vdoc-mkdocs/bin/activate)
    --repo-url URL         Specify the repository URL (default: https://github.com/voxel51/fiftyone.git)

To build the API docs along with the general docs you should use build.sh

Contributing

Please be sure to read our CONTRIBUTING guide.

Before you take on a big editing tasks we highly recommend:

1. Find an existing Github issue and start discussing what you would like to do
2. Create a new Github issue so we can discuss it with you
3. You can also come chat with us in Discord in the #docs channel - we are friendly and can give you good feedback.

Voxel51 Documentation by Voxel51 Inc is licensed under Creative Commons Attribution-ShareAlike 4.0 International