writing_docs.md

C++ docs

A high-level overview of writing and previewing the Rerun C++ documentation.

Getting started with docs

Serving the docs locally

Build the docs using:

pixi run -e cpp cpp-docs

They then can be locally viewed at rerun_cpp/docs/html/index.html

How versioned docs are generated and served

Our online documentation is generated in the same way as above and exists as GCS bucket hosted publicly on the https://ref.rerun.io domain.

Every commit that lands to main will generate bleeding edge documentation to docs/cpp/main. Releases will push to a version instead: docs/cpp/0.23.3

Writing docs

Docs are processed by the MkDoxy plugin which internally runs Doxygen to extra the docs.

There's many different ways of styling Doxygen compatible comments. We stick to the following styles:

• use /// for doc comments
• use \ for starting doxygen commands
• whenever possible prefer markdown over doxygen commands
• Don't use \brief, instead write a single line brief description at the top, leave a newline and continue with the detailed description.
• If you want to hide a class or method use \private
  • if you have to hide several entries at once, use:

  /// \cond private
  ...
  /// \endcond

• Avoid the use of groups when namespaces can be used instead
• Don't omit namespaces when referring to types in docs - instead of Collection use rerun::Collection. Both works usually but the latter makes it easier to understand what is meant.