Sphinx docs and Github Pages

.github/workflows/build_docs.yml

@@ -0,0 +1,53 @@
+# Workflow for building Sphinx docs and deploying to GH Pages
+name: Build Sphinx docs and deploy to GH Pages
+
+on:
+  # Runs on pushes
+  push # TODO: Update to push on main branch only before merging to main
+
+
+# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+# Allow only one concurrent deployment, cancelling in-progress runs.
+concurrency:
+  group: "pages"
+  cancel-in-progress: true
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - run: echo "The job was automatically triggered by a ${{ github.event_name }} event."
+      - run: echo "This job is now running on a ${{ runner.os }} server."
+      - run: echo "Running on branch ${{ github.ref }} of repository ${{ github.repository }}."
+      - name: Check out repository code.
+        uses: actions/checkout@v3
+      - name: Python environment setup
+        uses: actions/setup-python@v4
+        with:
+          python-version: 3.8
+      - name: Install dependencies.
+        run: |
+          sudo apt-get update
+          sudo apt-get install libsfml-dev
+          git submodule sync
+          git submodule update --init --recursive
+          python -m pip install -U pip
+          if [ -f requirements.txt ]; then pip install -r requirements.txt; fi
+          if [ -f requirements.dev.txt ]; then pip install -r requirements.dev.txt; fi
+          pip install -e .
+      - name: Build HTML docs
+        run: sphinx-build -b html docs/source/ docs/build/html
+      - name: Setup Pages
+        uses: actions/configure-pages@v3
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v1
+        with:
+          path: './docs/build/html' # Upload HTML docs only
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v2

.gitignore

@@ -44,3 +44,6 @@ dataset/
 
 # configs
 configs.json
+
+# Static doc files
+!docs/source/_static/*

.pre-commit-config.yaml

@@ -0,0 +1,20 @@
+repos:
+  - repo: https://github.com/mwouts/jupytext
+    rev: v1.14.0
+    hooks:
+      - id: jupytext
+        args: [--from, ipynb, --to, md:myst, --sync]
+
+  - repo: https://github.com/nbQA-dev/nbQA
+    rev: 1.7.0
+    hooks:
+      - id: nbqa-pyupgrade
+        args: ["--py38-plus"]
+      - id: nbqa-isort
+        args: ["--float-to-top"]
+      - id: nbqa-flake8
+
+  - repo: https://github.com/kynan/nbstripout
+    rev: 0.6.1
+    hooks:
+      - id: nbstripout

README.md

@@ -10,11 +10,11 @@ Using this rich data source, Nocturne contains a wide range of scenarios whose s
   <img src="https://user-images.githubusercontent.com/33672752/174244860-65865e95-0592-4279-ab5d-f40842092cc7.gif" width="250" height="250"/>
   <img src="https://user-images.githubusercontent.com/33672752/174244327-51f98409-4afd-424e-88f5-29892e89d796.gif" width="250" height="250"/>
 </p> -->
-![Intersection Scene with Obscured View](./docs/readme_files/git_intersection_combined.gif)
+![Intersection Scene with Obscured View](https://github.com/facebookresearch/nocturne/raw/main/docs/readme_files/git_intersection_combined.gif)
 
 Nocturne features a rich variety of scenes, ranging from parking lots, to merges, to roundabouts, to unsignalized intersections.
 
-![Intersection Scene with Obscured View](./docs/readme_files/nocturne_3_by_3_scenes.gif)
+![Intersection Scene with Obscured View](https://github.com/facebookresearch/nocturne/raw/main/docs/readme_files/nocturne_3_by_3_scenes.gif)
 
 More videos can be found [here](https://www.nathanlct.com/research/nocturne).
 

docs/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = source
+BUILDDIR      = build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/make.bat

@@ -0,0 +1,35 @@
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=source
+set BUILDDIR=build
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+	echo.
+	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+	echo.installed, then set the SPHINXBUILD environment variable to point
+	echo.to the full path of the 'sphinx-build' executable. Alternatively you
+	echo.may add the Sphinx directory to PATH.
+	echo.
+	echo.If you don't have Sphinx installed, grab it from
+	echo.https://www.sphinx-doc.org/
+	exit /b 1
+)
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+
+:end
+popd