C++ Doc improvements (#4212)

### What * Almost fixe_s #3974 * Follow-up of #4191 A few remaining items & polish for the C++ docs. Now uploaded to gh-pages as well on push to main (🤞 it works.......) Commit by commit! ### Checklist * [x] I have read and agree to [Contributor Guide](https://github.com/rerun-io/rerun/blob/main/CONTRIBUTING.md) and the [Code of Conduct](https://github.com/rerun-io/rerun/blob/main/CODE_OF_CONDUCT.md) * [x] I've included a screenshot or gif (if applicable) * [x] I have tested [demo.rerun.io](https://demo.rerun.io/pr/4212) (if applicable) * [x] The PR title and labels are set such as to maximize their usefulness for the next release's CHANGELOG - [PR Build Summary](https://build.rerun.io/pr/4212) - [Docs preview](https://rerun.io/preview/4d098307e728ccea06f408df01f700dda18739c1/docs)  - [Examples preview](https://rerun.io/preview/4d098307e728ccea06f408df01f700dda18739c1/examples)  - [Recent benchmark results](https://ref.rerun.io/dev/bench/) - [Wasm size tracking](https://ref.rerun.io/dev/sizes/)
rerun-io · Nov 13, 2023 · 23a15b5 · 23a15b5
1 parent 6ee3c6a
commit 23a15b5
Show file tree

Hide file tree

Showing 10 changed files with 89 additions and 151 deletions.
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
@@ -197,7 +197,7 @@ jobs:
     with:
       CONCURRENCY: ${{ github.ref_name }}
       PY_DOCS_VERSION_NAME: ${{ inputs.release-type == 'final' && needs.version.outputs.final || 'dev' }}
-      RS_DOCS_VERSION_NAME: ${{ inputs.release-type == 'final' && 'stable' || 'dev' }}
+      RS_AND_CPP_DOCS_VERSION_NAME: ${{ inputs.release-type == 'final' && 'stable' || 'dev' }}
       UPDATE_LATEST: ${{ inputs.release-type == 'final' }}
       RELEASE_COMMIT: ${{ needs.version.outputs.release-commit }}
     secrets: inherit
@@ -270,7 +270,8 @@ jobs:
     if: inputs.release-type == 'final'
     needs:
       [
-        version, update-docs,
+        version,
+        update-docs,
         publish-crates,
         publish-wheels,
         publish-web,
@@ -296,7 +297,8 @@ jobs:
     if: inputs.release-type == 'alpha' || inputs.release-type == 'final'
     needs:
       [
-        version, update-docs,
+        version,
+        update-docs,
         publish-crates,
         publish-wheels,
         publish-web,
@@ -353,7 +355,8 @@ jobs:
     name: "Link to artifacts"
     needs:
       [
-        version, update-docs,
+        version,
+        update-docs,
         publish-crates,
         publish-wheels,
         publish-web,

diff --git a/.github/workflows/reusable_deploy_docs.yml b/.github/workflows/reusable_deploy_docs.yml
@@ -9,7 +9,7 @@ on:
       PY_DOCS_VERSION_NAME:
         required: true
         type: string
-      RS_DOCS_VERSION_NAME:
+      RS_AND_CPP_DOCS_VERSION_NAME:
         required: false
         type: string
         default: "head"
@@ -163,7 +163,59 @@ jobs:
       - name: Deploy the docs
         run: |
           git fetch
-          python3 -m ghp_import -n -p -x docs/rust/${{ inputs.RS_DOCS_VERSION_NAME }} target/doc/ -m "Update the rust docs"
+          python3 -m ghp_import -n -p -x docs/rust/${{ inputs.RS_AND_CPP_DOCS_VERSION_NAME }} target/doc/ -m "Update the rust docs"
+
+  cpp-deploy-docs:
+    name: Cpp
+    runs-on: ubuntu-latest
+    steps:
+      - name: Show context
+        run: |
+          echo "GITHUB_CONTEXT": $GITHUB_CONTEXT
+          echo "JOB_CONTEXT": $JOB_CONTEXT
+          echo "INPUTS_CONTEXT": $INPUTS_CONTEXT
+          echo "ENV_CONTEXT": $ENV_CONTEXT
+        env:
+          ENV_CONTEXT: ${{ toJson(env) }}
+          GITHUB_CONTEXT: ${{ toJson(github) }}
+          JOB_CONTEXT: ${{ toJson(job) }}
+          INPUTS_CONTEXT: ${{ toJson(inputs) }}
+
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0 # Don't do a shallow clone since we need to push gh-pages
+          ref: ${{ inputs.RELEASE_COMMIT || (github.event_name == 'pull_request' && github.event.pull_request.head.ref || '') }}
+
+      - uses: prefix-dev/[email protected]
+        with:
+          pixi-version: v0.6.0
+          cache: true
+
+      - name: Doxygen C++ docs
+        run: pixi run cpp-docs
+
+      - name: Set up git author
+        run: |
+          remote_repo="https://${GITHUB_TOKEN}@github.com/${GITHUB_REPOSITORY}.git"
+          git config --global user.name "${GITHUB_ACTOR}"
+          git config --global user.email "${GITHUB_ACTOR}@users.noreply.github.com"
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Set up ghp-import
+        run: pip install ghp-import
+
+        # TODO(andreas): Do we need this?
+      # - name: Patch in a redirect page
+      #   run: echo "<meta http-equiv=\"refresh\" content=\"0; url=${REDIRECT_CRATE}\">" > target/doc/index.html
+      #   env:
+      #     REDIRECT_CRATE: rerun
+
+      # See: https://github.com/c-w/ghp-import
+      - name: Deploy the docs
+        run: |
+          git fetch
+          python3 -m ghp_import -n -p -x docs/cpp/${{ inputs.RS_AND_CPP_DOCS_VERSION_NAME }} rerun_cpp/docs/html/ -m "Update the C++ docs"
 
   redeploy-rerun-io:
     runs-on: ubuntu-latest
@@ -180,4 +232,3 @@ jobs:
           vercel_team_name: ${{ vars.VERCEL_TEAM_NAME }}
           vercel_project_name: ${{ vars.VERCEL_PROJECT_NAME }}
           release_commit: ${{ inputs.RELEASE_COMMIT }}
-
diff --git a/docs/content/reference/cpp.md b/docs/content/reference/cpp.md
@@ -0,0 +1,5 @@
+---
+title: 🌊 C++ APIs
+order: 10
+redirect: https://ref.rerun.io/docs/cpp?speculative-link
+---
diff --git a/docs/content/reference/migration-0-9.md b/docs/content/reference/migration-0-9.md
@@ -1,6 +1,6 @@
 ---
 title: Migration to 0.9
-order: 10
+order: 12
 ---
 
 Rerun-0.9 introduces a new set of type-oriented logging APIs built on top of an updated, more concrete,

diff --git a/docs/content/reference/rust.md b/docs/content/reference/rust.md
@@ -1,5 +1,5 @@
 ---
 title: 🦀 Rust APIs
-order: 10
+order: 11
 redirect: https://docs.rs/rerun/
 ---
diff --git a/docs/cspell.json b/docs/cspell.json
@@ -32,6 +32,7 @@
     "backbuffer",
     "backprojection",
     "barebone",
+    "Bazel",
     "Bgra",
     "Bhat",
     "bindgen",

diff --git a/pixi.toml b/pixi.toml
@@ -76,7 +76,7 @@ cpp-log-benchmark = { cmd = "export RERUN_STRICT=1 && ./build/tests/cpp/log_benc
   "cpp-build-log-benchmark",
 ] }
 cpp-build-and-test-all = { depends_on = ["cpp-build-all", "cpp-test"] }
-cpp-docs = { cmd = "doxygen rerun_cpp/docs/Doxyfile" }
+cpp-docs = { cmd = "doxygen rerun_cpp/docs/Doxyfile && echo '***************\nSuccess!\nOpen ./rerun_cpp/docs/html/index.html in your browser.'" }
 
 [target.win-64.tasks]
 cpp-prepare-msvc = "cmake -G 'Visual Studio 17 2022' -B build-msvc -S ."

diff --git a/rerun_cpp/README.md b/rerun_cpp/README.md
@@ -4,6 +4,13 @@ The Rerun C++ SDK allows logging data to Rerun directly from C++.
 
 Read the [getting started guide](https://www.rerun.io/docs/getting-started/cpp) for information on how to use the Rerun C++ SDK.
 
+## Examples
+
+As general entry point for Rerun examples check the [examples page](https://www.rerun.io/examples) on our website.
+All C++ examples can be found [directly in the Rerun repository](https://github.com/rerun-io/rerun/tree/latest/examples/cpp).
+Additionally, each [archetype's documentation](https://www.rerun.io/docs/reference/types) comes with at least one small self-contained code example.
+
+
 ## Building Blocks
 
 The most important type in the SDK is the `rerun::RecordingStream`.
@@ -18,7 +25,6 @@ If you include `rerun.hpp`, all archetypes and selected components become part o
 
 Check the [general doc page on types](https://www.rerun.io/docs/reference/types) to learn more.
 
-
 ## Build & Distribution
 
 ### Overview
@@ -40,7 +46,7 @@ From a build system perspective, the SDK consists of three dependencies:
   * See [Install arrow-cpp](https://www.rerun.io/docs/howto/arrow-cpp-install) for how to install this library
 
 
-### SDK bundle `rerun_cpp_sdk.zip`
+### SDK bundle (rerun_cpp_sdk.zip)
 
 For convenience, Rerun provides a C++ SDK bundle with every release.
 (this includes our regular [Development Builds](https://github.com/rerun-io/rerun/releases/tag/prerelease)!)
@@ -57,13 +63,19 @@ how to use the SDK's `CMakeLists.txt` and an overview over all CMake configurati
 
 ### Without CMake
 
-In order to build without CMake, you have to add all files from the [src/](https://github.com/rerun-io/rerun/tree/latest/rerun_cpp/src/) folder
+We don't have first class support for other build systems yet,
+but it should be possible to setup Rerun C++ without CMake fairly easily:
+
+You have to add all files from the [src/](https://github.com/rerun-io/rerun/tree/latest/rerun_cpp/src/) folder
 either directly to your project or a library.
 In addition, you need to link the `rerun_c` libraries and the [Arrow C++ library](https://arrow.apache.org/docs/cpp/index.html).
+For more information on how to install Arrow, see [Install arrow-cpp](https://www.rerun.io/docs/howto/arrow-cpp-install).
 
 Make sure to compile with C++17 or newer.
 
-For more information on how to install Arrow, see [Install arrow-cpp](https://www.rerun.io/docs/howto/arrow-cpp-install).
+#### Bazel
+
+There's a user provided minimal Bazel example here: https://github.com/kyle-figure/bazel-minimal-rerun/
 
 
 ## Development in the Rerun repository

diff --git a/rerun_cpp/docs/Doxyfile b/rerun_cpp/docs/Doxyfile
@@ -1413,43 +1413,6 @@ HTML_INDEX_NUM_ENTRIES = 100
 
 GENERATE_DOCSET        = NO
 
-# This tag determines the name of the docset feed. A documentation feed provides
-# an umbrella under which multiple documentation sets from a single provider
-# (such as a company or product suite) can be grouped.
-# The default value is: Doxygen generated docs.
-# This tag requires that the tag GENERATE_DOCSET is set to YES.
-
-DOCSET_FEEDNAME        = "Doxygen generated docs"
-
-# This tag determines the URL of the docset feed. A documentation feed provides
-# an umbrella under which multiple documentation sets from a single provider
-# (such as a company or product suite) can be grouped.
-# This tag requires that the tag GENERATE_DOCSET is set to YES.
-
-DOCSET_FEEDURL         =
-
-# This tag specifies a string that should uniquely identify the documentation
-# set bundle. This should be a reverse domain-name style string, e.g.
-# com.mycompany.MyDocSet. Doxygen will append .docset to the name.
-# The default value is: org.doxygen.Project.
-# This tag requires that the tag GENERATE_DOCSET is set to YES.
-
-DOCSET_BUNDLE_ID       = org.doxygen.Project
-
-# The DOCSET_PUBLISHER_ID tag specifies a string that should uniquely identify
-# the documentation publisher. This should be a reverse domain-name style
-# string, e.g. com.mycompany.MyDocSet.documentation.
-# The default value is: org.doxygen.Publisher.
-# This tag requires that the tag GENERATE_DOCSET is set to YES.
-
-DOCSET_PUBLISHER_ID    = org.doxygen.Publisher
-
-# The DOCSET_PUBLISHER_NAME tag identifies the documentation publisher.
-# The default value is: Publisher.
-# This tag requires that the tag GENERATE_DOCSET is set to YES.
-
-DOCSET_PUBLISHER_NAME  = Publisher
-
 # If the GENERATE_HTMLHELP tag is set to YES then doxygen generates three
 # additional HTML index files: index.hhp, index.hhc, and index.hhk. The
 # index.hhp is a project file that can be read by Microsoft's HTML Help Workshop
@@ -1472,49 +1435,6 @@ DOCSET_PUBLISHER_NAME  = Publisher
 
 GENERATE_HTMLHELP      = NO
 
-# The CHM_FILE tag can be used to specify the file name of the resulting .chm
-# file. You can add a path in front of the file if the result should not be
-# written to the html output directory.
-# This tag requires that the tag GENERATE_HTMLHELP is set to YES.
-
-CHM_FILE               =
-
-# The HHC_LOCATION tag can be used to specify the location (absolute path
-# including file name) of the HTML help compiler (hhc.exe). If non-empty,
-# doxygen will try to run the HTML help compiler on the generated index.hhp.
-# The file has to be specified with full path.
-# This tag requires that the tag GENERATE_HTMLHELP is set to YES.
-
-HHC_LOCATION           =
-
-# The GENERATE_CHI flag controls if a separate .chi index file is generated
-# (YES) or that it should be included in the main .chm file (NO).
-# The default value is: NO.
-# This tag requires that the tag GENERATE_HTMLHELP is set to YES.
-
-GENERATE_CHI           = NO
-
-# The CHM_INDEX_ENCODING is used to encode HtmlHelp index (hhk), content (hhc)
-# and project file content.
-# This tag requires that the tag GENERATE_HTMLHELP is set to YES.
-
-CHM_INDEX_ENCODING     =
-
-# The BINARY_TOC flag controls whether a binary table of contents is generated
-# (YES) or a normal table of contents (NO) in the .chm file. Furthermore it
-# enables the Previous and Next buttons.
-# The default value is: NO.
-# This tag requires that the tag GENERATE_HTMLHELP is set to YES.
-
-BINARY_TOC             = NO
-
-# The TOC_EXPAND flag can be set to YES to add extra items for group members to
-# the table of contents of the HTML help documentation and to the tree view.
-# The default value is: NO.
-# This tag requires that the tag GENERATE_HTMLHELP is set to YES.
-
-TOC_EXPAND             = NO
-
 # The SITEMAP_URL tag is used to specify the full URL of the place where the
 # generated documentation will be placed on the server by the user during the
 # deployment of the documentation. The generated sitemap is called sitemap.xml
@@ -1534,61 +1454,6 @@ SITEMAP_URL            =
 
 GENERATE_QHP           = NO
 
-# If the QHG_LOCATION tag is specified, the QCH_FILE tag can be used to specify
-# the file name of the resulting .qch file. The path specified is relative to
-# the HTML output folder.
-# This tag requires that the tag GENERATE_QHP is set to YES.
-
-QCH_FILE               =
-
-# The QHP_NAMESPACE tag specifies the namespace to use when generating Qt Help
-# Project output. For more information please see Qt Help Project / Namespace
-# (see:
-# https://doc.qt.io/archives/qt-4.8/qthelpproject.html#namespace).
-# The default value is: org.doxygen.Project.
-# This tag requires that the tag GENERATE_QHP is set to YES.
-
-QHP_NAMESPACE          = org.doxygen.Project
-
-# The QHP_VIRTUAL_FOLDER tag specifies the namespace to use when generating Qt
-# Help Project output. For more information please see Qt Help Project / Virtual
-# Folders (see:
-# https://doc.qt.io/archives/qt-4.8/qthelpproject.html#virtual-folders).
-# The default value is: doc.
-# This tag requires that the tag GENERATE_QHP is set to YES.
-
-QHP_VIRTUAL_FOLDER     = doc
-
-# If the QHP_CUST_FILTER_NAME tag is set, it specifies the name of a custom
-# filter to add. For more information please see Qt Help Project / Custom
-# Filters (see:
-# https://doc.qt.io/archives/qt-4.8/qthelpproject.html#custom-filters).
-# This tag requires that the tag GENERATE_QHP is set to YES.
-
-QHP_CUST_FILTER_NAME   =
-
-# The QHP_CUST_FILTER_ATTRS tag specifies the list of the attributes of the
-# custom filter to add. For more information please see Qt Help Project / Custom
-# Filters (see:
-# https://doc.qt.io/archives/qt-4.8/qthelpproject.html#custom-filters).
-# This tag requires that the tag GENERATE_QHP is set to YES.
-
-QHP_CUST_FILTER_ATTRS  =
-
-# The QHP_SECT_FILTER_ATTRS tag specifies the list of the attributes this
-# project's filter section matches. Qt Help Project / Filter Attributes (see:
-# https://doc.qt.io/archives/qt-4.8/qthelpproject.html#filter-attributes).
-# This tag requires that the tag GENERATE_QHP is set to YES.
-
-QHP_SECT_FILTER_ATTRS  =
-
-# The QHG_LOCATION tag can be used to specify the location (absolute path
-# including file name) of Qt's qhelpgenerator. If non-empty doxygen will try to
-# run qhelpgenerator on the generated .qhp file.
-# This tag requires that the tag GENERATE_QHP is set to YES.
-
-QHG_LOCATION           =
-
 # If the GENERATE_ECLIPSEHELP tag is set to YES, additional index files will be
 # generated, together with the HTML files, they form an Eclipse help plugin. To
 # install this plugin and make it available under the help contents menu in

diff --git a/rerun_cpp/src/rerun.hpp b/rerun_cpp/src/rerun.hpp
@@ -16,9 +16,10 @@
 #include "rerun/sdk_info.hpp"
 #include "rerun/spawn.hpp"
 
-// Archetypes are the quick-and-easy default way of logging data to Rerun.
-// Make them available in the rerun namespace.
+/// All Rerun C++ types and functions are in the `rerun` namespace or one of its nested namespaces.
 namespace rerun {
+    // Archetypes are the quick-and-easy default way of logging data to Rerun.
+    // Make them available in the rerun namespace.
     using namespace archetypes;
 
     // Also import any component or datatype that has a unique name: