From 30fccb3bc6562e18eaa27dbadb4b66660c99df6b Mon Sep 17 00:00:00 2001 From: Andreas Reich Date: Fri, 10 Nov 2023 18:17:38 +0100 Subject: [PATCH 01/10] pixi doc command now tells you where the docs are --- pixi.toml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pixi.toml b/pixi.toml index 6df77f5f0495..a952303cf2dd 100644 --- 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 ." From a9d723df6d39bd75a6645e618f45635bd5512e83 Mon Sep 17 00:00:00 2001 From: Andreas Reich Date: Fri, 10 Nov 2023 18:33:49 +0100 Subject: [PATCH 02/10] remove some stuff from doxyfile that likely won't ever be needed --- rerun_cpp/docs/Doxyfile | 135 ---------------------------------------- 1 file changed, 135 deletions(-) diff --git a/rerun_cpp/docs/Doxyfile b/rerun_cpp/docs/Doxyfile index 17ed7b775d75..2c36ee3edb02 100644 --- 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 From 8940f0e7e8635c6db8b7077fa543c698dc9115e5 Mon Sep 17 00:00:00 2001 From: Andreas Reich Date: Mon, 13 Nov 2023 10:36:42 +0100 Subject: [PATCH 03/10] fix empty namespaces list on docs --- rerun_cpp/src/rerun.hpp | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/rerun_cpp/src/rerun.hpp b/rerun_cpp/src/rerun.hpp index b3241cf7d813..438270b8a9e8 100644 --- 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: From b62bb05c07888d8f7d2d31eece658593533dda3d Mon Sep 17 00:00:00 2001 From: Andreas Reich Date: Mon, 13 Nov 2023 10:43:25 +0100 Subject: [PATCH 04/10] more build instructions, link bazel example --- rerun_cpp/README.md | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) diff --git a/rerun_cpp/README.md b/rerun_cpp/README.md index 1c0d92016487..24fe8b5b5422 100644 --- a/rerun_cpp/README.md +++ b/rerun_cpp/README.md @@ -57,13 +57,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 From 9d3bf649f710ed78b24a30c252bebe31c766f4fe Mon Sep 17 00:00:00 2001 From: Andreas Reich Date: Mon, 13 Nov 2023 10:47:15 +0100 Subject: [PATCH 05/10] example docs on rerun_cpp readme --- rerun_cpp/README.md | 10 +++++++++- 1 file changed, 9 insertions(+), 1 deletion(-) diff --git a/rerun_cpp/README.md b/rerun_cpp/README.md index 24fe8b5b5422..dd309b10ce0d 100644 --- a/rerun_cpp/README.md +++ b/rerun_cpp/README.md @@ -4,6 +4,15 @@ 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 +27,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 From 0edb59bf0df359cc8d45c2b584ec290550729693 Mon Sep 17 00:00:00 2001 From: Andreas Reich Date: Mon, 13 Nov 2023 11:03:14 +0100 Subject: [PATCH 06/10] small readme fixes to make it look better on doxygen --- rerun_cpp/README.md | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/rerun_cpp/README.md b/rerun_cpp/README.md index dd309b10ce0d..851c60717551 100644 --- a/rerun_cpp/README.md +++ b/rerun_cpp/README.md @@ -7,9 +7,7 @@ Read the [getting started guide](https://www.rerun.io/docs/getting-started/cpp) ## 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. @@ -48,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)!) From 1e13f7b2cc3ab5ab1ad909a29eb2b5416a56f3b7 Mon Sep 17 00:00:00 2001 From: Andreas Reich Date: Mon, 13 Nov 2023 11:08:18 +0100 Subject: [PATCH 07/10] add gh pages cpp doc upload --- .github/workflows/reusable_deploy_docs.yml | 52 +++++++++++++++++++++- 1 file changed, 51 insertions(+), 1 deletion(-) diff --git a/.github/workflows/reusable_deploy_docs.yml b/.github/workflows/reusable_deploy_docs.yml index 222656ed9451..bdd8ea9c3fb0 100644 --- a/.github/workflows/reusable_deploy_docs.yml +++ b/.github/workflows/reusable_deploy_docs.yml @@ -165,6 +165,57 @@ jobs: git fetch python3 -m ghp_import -n -p -x docs/rust/${{ inputs.RS_DOCS_VERSION_NAME }} target/doc/ -m "Update the rust docs" + cpp-deploy-docs: + name: Rust + 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/setup-pixi@v0.3.0 + 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 + + - name: Patch in a redirect page + run: echo "" > 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_DOCS_VERSION_NAME }} rerun_cpp/docs/html/ -m "Update the C++ docs" + redeploy-rerun-io: runs-on: ubuntu-latest if: inputs.UPDATE_LATEST @@ -180,4 +231,3 @@ jobs: vercel_team_name: ${{ vars.VERCEL_TEAM_NAME }} vercel_project_name: ${{ vars.VERCEL_PROJECT_NAME }} release_commit: ${{ inputs.RELEASE_COMMIT }} - From 5e6db314c4a9a57713605b10b81883ebc8faf534 Mon Sep 17 00:00:00 2001 From: Andreas Reich Date: Mon, 13 Nov 2023 11:19:53 +0100 Subject: [PATCH 08/10] cspell ignore word --- docs/cspell.json | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/cspell.json b/docs/cspell.json index 60af1eaa4c92..ca531619a7fb 100644 --- a/docs/cspell.json +++ b/docs/cspell.json @@ -32,6 +32,7 @@ "backbuffer", "backprojection", "barebone", + "Bazel", "Bgra", "Bhat", "bindgen", From 4d098307e728ccea06f408df01f700dda18739c1 Mon Sep 17 00:00:00 2001 From: Andreas Reich Date: Mon, 13 Nov 2023 11:41:04 +0100 Subject: [PATCH 09/10] add speculative cpp doc link to rerun.io/docs --- docs/content/reference/cpp.md | 5 +++++ docs/content/reference/migration-0-9.md | 2 +- docs/content/reference/rust.md | 2 +- 3 files changed, 7 insertions(+), 2 deletions(-) create mode 100644 docs/content/reference/cpp.md diff --git a/docs/content/reference/cpp.md b/docs/content/reference/cpp.md new file mode 100644 index 000000000000..add94256b82a --- /dev/null +++ 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 index 921a5c9a5e67..b0e81e83ceee 100644 --- 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 index 298774932247..658b8e5086b8 100644 --- 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/ --- From 8547988e7d95c1df28c20b701581094e67f29780 Mon Sep 17 00:00:00 2001 From: Andreas Reich Date: Mon, 13 Nov 2023 16:30:46 +0100 Subject: [PATCH 10/10] fixup cpp doc deploy --- .github/workflows/release.yml | 11 +++++++---- .github/workflows/reusable_deploy_docs.yml | 17 +++++++++-------- 2 files changed, 16 insertions(+), 12 deletions(-) diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index 69beca125d41..4da4ff7c1cc8 100644 --- 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 index bdd8ea9c3fb0..26952ba2e00f 100644 --- 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,10 +163,10 @@ 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: Rust + name: Cpp runs-on: ubuntu-latest steps: - name: Show context @@ -205,16 +205,17 @@ jobs: - name: Set up ghp-import run: pip install ghp-import - - name: Patch in a redirect page - run: echo "" > target/doc/index.html - env: - REDIRECT_CRATE: rerun + # TODO(andreas): Do we need this? + # - name: Patch in a redirect page + # run: echo "" > 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_DOCS_VERSION_NAME }} rerun_cpp/docs/html/ -m "Update the C++ docs" + 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