c docs to docs.comma.ai

.dockerignore

@@ -36,3 +36,4 @@ xx/projects
 !xx/projects/map3d
 xx/ops
 xx/junk
+docs/build

.gitignore

@@ -8,6 +8,7 @@ venv/
 .overlay_consistent
 .sconsign.dblite
 .vscode*
+.devcontainer/
 model2.png
 a.out
 .hypothesis

Pipfile

@@ -28,6 +28,7 @@ pyprof2calltree = "*"
 reverse_geocoder = "*"
 scipy = "*"
 sphinx = "*"
+breathe = "*"
 sphinx-rtd-theme = "*"
 subprocess32 = "*"
 tenacity = "*"

docs/CMakeLists.txt

@@ -0,0 +1,33 @@
+########################################################################
+# CMake build nstructions for https://docs.comma.ai/
+#
+# instructions (local build): opening `build/html/index.html` in a browser
+#   mkdir build && cd build && cmake ../ && cmake --build . -- -j$(nproc)
+#
+# instructions (docker build): http://localhost:3000/
+#   cd openpilot/
+#   docker build -t ghcr.io/commaai/openpilot-docs:latest -f docs/docker/Dockerfile .
+#   docker run --rm -d 3000:80 ghcr.io/commaai/openpilot-docs:latest
+########################################################################
+
+cmake_minimum_required(VERSION 3.10)
+project(docs
+    DESCRIPTION "comma.ai developer documentation"
+    HOMEPAGE_URL https://docs.comma.ai/
+)
+
+find_package(PkgConfig REQUIRED)
+list(INSERT CMAKE_MODULE_PATH 0 ${CMAKE_SOURCE_DIR}/cmake/Modules)
+
+# set OPENPILOT_ROOT
+find_package(Git QUIET)
+execute_process(
+    COMMAND git rev-parse --show-toplevel
+    WORKING_DIRECTORY ${CMAKE_SOURCE_DIR}
+    OUTPUT_VARIABLE OPENPILOT_ROOT
+    OUTPUT_STRIP_TRAILING_WHITESPACE
+)
+set(OPENPILOT_ROOT ${OPENPILOT_ROOT} CACHE INTERNAL "openpilot root directory")
+
+# add_subdirectory(doxygen)
+add_subdirectory(sphinx)

docs/cmake/Modules/FindSphinx.cmake

@@ -0,0 +1,30 @@
+########################################################################
+# Sets the following cmake variables when find_package(Sphinx) is called:
+#  - SPHINX_FOUND : TRUE if SPHINX binaries are found, FALSE otherwise
+#  - SPHINX_BUILD_EXEC : path to `sphinx-build`
+#  - SPHINX_API_EXEC : path to `sphinx-apidoc`
+########################################################################
+
+# Handle standard arguments to find_package like REQUIRED and QUIET
+include(FindPackageHandleStandardArgs)
+
+if(NOT SPHINX_FOUND)
+
+    find_program(SPHINX_BUILD_EXEC
+        NAMES sphinx-build
+        DOC "path to sphinx-build executable"
+    )
+    find_package_handle_standard_args(Sphinx "Failed to find sphinx-build executable" SPHINX_BUILD_EXEC )
+
+    find_program(SPHINX_API_EXEC
+        NAMES sphinx-apidoc
+        DOC "path to sphinx-apidoc executable"
+    )
+    find_package_handle_standard_args(Sphinx "Failed to find sphinx-apidoc executable" SPHINX_API_EXEC )
+
+    if(SPHINX_BUILD_EXEC AND SPHINX_API_EXEC)
+        set(SPHINX_FOUND TRUE CACHE INTERNAL "Found Sphinx execs")
+    endif(SPHINX_BUILD_EXEC AND SPHINX_API_EXEC)
+
+    mark_as_advanced(SPHINX_FOUND)
+endif(NOT SPHINX_FOUND)

docs/docker/Dockerfile

@@ -2,10 +2,10 @@ FROM ghcr.io/commaai/openpilot-base:latest
 
 ENV PYTHONUNBUFFERED 1
 
-ENV OPENPILOT_PATH /home/batman/openpilot/
+ENV OPENPILOT_PATH /home/batman/openpilot
 ENV PYTHONPATH ${OPENPILOT_PATH}:${PYTHONPATH}
 
-RUN mkdir -p ${OPENPILOT_PATH}
+RUN mkdir -p ${OPENPILOT_PATH}/
 WORKDIR ${OPENPILOT_PATH}
 
 COPY Pipfile Pipfile.lock $OPENPILOT_PATH
@@ -22,7 +22,6 @@ COPY ./site_scons ${OPENPILOT_PATH}/site_scons
 COPY ./laika ${OPENPILOT_PATH}/laika
 COPY ./laika_repo ${OPENPILOT_PATH}/laika_repo
 COPY ./rednose ${OPENPILOT_PATH}/rednose
-COPY ./rednose_repo ${OPENPILOT_PATH}/rednose_repo
 COPY ./tools ${OPENPILOT_PATH}/tools
 COPY ./release ${OPENPILOT_PATH}/release
 COPY ./common ${OPENPILOT_PATH}/common
@@ -34,11 +33,13 @@ COPY ./*.md ${OPENPILOT_PATH}/
 
 RUN scons -j$(nproc)
 
+RUN apt update && apt install -y doxygen
+
 COPY ./docs ${OPENPILOT_PATH}/docs
 RUN git init .
 WORKDIR ${OPENPILOT_PATH}/docs
-RUN make html
+RUN mkdir build && cd build && cmake ../ && make -j$(nproc)
 
 FROM nginx:1.21
-COPY --from=0  /home/batman/openpilot/build/docs/html /usr/share/nginx/html
+COPY --from=0  /home/batman/openpilot/docs/build/html /usr/share/nginx/html
 COPY ./docs/docker/nginx.conf /etc/nginx/conf.d/default.conf

docs/doxygen/CMakeLists.txt

@@ -0,0 +1,42 @@
+###############################################
+# build procedures to document _all_ c methods
+# `sphinx-build` may not play well sometimes...
+################################################
+
+find_package(Doxygen REQUIRED)
+
+file(TO_NATIVE_PATH ${OPENPILOT_ROOT} top_srcdir)
+file(TO_NATIVE_PATH ${CMAKE_BINARY_DIR} top_builddir)
+file(TO_NATIVE_PATH ${OPENPILOT_ROOT} abs_top_srcdir)
+file(TO_NATIVE_PATH ${CMAKE_BINARY_DIR} abs_top_builddir)
+
+set(HAVE_DOT ${DOXYGEN_DOT_FOUND} CACHE INTERNAL "graphviz is installed to generate doxy graphics")
+
+set(DOXYGEN_IN ${CMAKE_CURRENT_SOURCE_DIR}/Doxyfile.in)
+set(DOXYGEN_OUT ${CMAKE_CURRENT_BINARY_DIR}/Doxyfile)
+
+configure_file(
+    ${DOXYGEN_IN}
+    ${DOXYGEN_OUT}
+    @ONLY
+)
+
+set(DOXY_BUILD_DIR ${CMAKE_CURRENT_BINARY_DIR}/xml CACHE INTERNAL "Path to doxygen build files")
+
+########################################################################
+# setup doxy_build target
+# generates c/c++ .xml files -> copies to root html/xml
+########################################################################
+add_custom_command(
+    OUTPUT doxy_xml
+    COMMAND ${DOXYGEN_EXECUTABLE} ${DOXYGEN_OUT}
+    COMMAND ${CMAKE_COMMAND} -E copy_directory ${CMAKE_CURRENT_BINARY_DIR}/xml ${CMAKE_BINARY_DIR}/html/xml
+    WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}
+    COMMENT "generating C/C++ documentation with doxygen..."
+    VERBATIM
+)
+
+add_custom_target(doxy_build
+    ALL
+    DEPENDS doxy_xml
+)