Alan's Q4 Update 2023

By Alan Freitas on
Jan 12, 2024

Summary

MrDocs

Over the last quarter, we continued to work intensely on MrDocs, a documentation generator for C++ projects. I’ve been overseeing and reviewing all the work done by the other contributors in the project. Besides the work done by Krystian, Fernando also joined the project as a contributor.

We’ve been working on making the project at least as competitive as Doxygen + Docca, so we can start using it in a subset of Boost libraries. In this process, we have also been improving usability and documentation, considering feedback we received.

In particular, work in Q4 included:

  • Improvements to the documentation, both in javadocs and exposition
  • Reducing technical debt, including extending APIs and problems with handlebars templates
  • Updating CI workflows in coordination with the C++ Github Actions project
  • Usability improvements, including tools relative to installed executable and many new features for templates
  • Fixes and improvements to installation procedure
  • Features such as symbols with links to repositories and many new sections in templates
  • Auxiliary utilities, such as a complete implementation of std::expected for the project
  • Generating binaries for the new LLVM version and updating the documentation
  • Improvements to build scripts with CMake presets and vcpkg manifest files

In parallel, Boost.URL has integrated MrDocs, and is temporarily generating the documentation with both Doxygen+Docca and Antora+MrDocs. The documentation includes an extension to collect reference pages generated by MrDocs and include them in the Antora documentation. A preview of the documentation generated by MrDocs is available at https://792.urlantora.prtest2.cppalliance.org/site/url/index.html.

In general, I’ve been responsible for:

  • setting up and maintaining CI for the project;
  • MrDocs and LLVM release binaries;
  • build scripts;
  • setting up and integrating dependencies;
  • setting up and deploying the Antora toolchains and documentation to the project website;
  • working on supporting libraries; and
  • supervising and reviewing the work done by other contributors (Krystian and Fernando);
  • fixing bugs.

Handlebars

MrDocs includes a support library that reimplements the Handlebars template engine in C++. This module is used to generate documentation from templates. This continued to be the MrDocs support library in which I have been investing most of my time.

MrDocs also includes a support library called “DOM” that provides a C++ interface to type-erased property trees, such as JSON and Javascript Objects. This module is used by MrDocs to create opaque representations of property trees that can be used by the Handlebars engine and other library functions. Such representations can come from a variety of sources, including JSON files, Javascript objects, and internal C++ objects with information parsed by MrDocs.

In Q4, a number of improvements relevant to MrDocs were made to the Handlebars and DOM libraries. The main feature is the addition of complete bindings for Javascript objects, arrays, and functions. The C++/JavaScript bindings work both ways, so that C++ objects can be used in Javascript and Javascript objects can be used in C++. Unit tests for the DOM were also included to complement the Handlebars unit tests.

These changes enabled the original implementation of handlebars.js to be completely removed from the project.

Boost Libraries

As in other quarters, the Boost Library in which I have been investing most of my time is Boost.URL. The library is in maintenance mode since our focus shifted to MrDocs, but there is a constant demand for work fixing bugs and improving the documentation.

In Q4, Boost.URL has integrated MrDocs, and is temporarily generating the documentation with both Doxygen+Docca and Antora+MrDocs:

  • All the content in the QuickBook documentation has been rewritten in asciidoc format. Alternatives have been developed to replace special QuickBook features, such as snippets.
  • The Boost.URL repository now includes an extension to automatically find or download MrDocs and use it to collect reference pages generated by MrDocs. The reference pages are aggregates as logical files in the Antora system, which includes them in the Antora documentation.

A preview of the documentation generated by MrDocs is available at https://792.urlantora.prtest2.cppalliance.org/site/url/index.html.

Besides the integration with MrDocs, work in Q4 included:

  • Improvements, simplifications, and a number of extensions to CI
  • Fixed previous design choices that were incompatible with the super-project
  • Fixes to build scripts to support for more compilers
  • Extended integration tests to cover all cases described by the super-project CMake scripts
  • Fixes to algorithms, such as the parse_query and format functions
  • GDB pretty printers are now provided

Many improvements had to be coordinated with the C++ Github Actions project, which had new features implemented for these use cases.

In general, I’ve been responsible for:

  • upgrading CI, mostly coordinating with the C++ Github Actions;
  • maintaining, simplifying, and updating build scripts;
  • integrating more spec tests, such as the Ada tests included more recently;
  • including more examples, such as the more recent sanitize-URL example;
  • fixing documentation content that is out of date; and
  • fixing bugs.

Besides Boost.URL, as usual, I’ve been overseeing and fixing smaller issues with other boost libraries. In Q4, only some small work in Boost.StaticString was necessary.

Boost Release Tools

Over the last quarter, I’ve been working on the integration of toolchains I developed into the Boost Release Tools to add support for features desired for the new website. In Q3, I previously included Antora support in the release tools and this has already been deployed in the official Boost release 1.84.0.

In Q4, I opened a pull request to include support for archive variants in the release tools. This pull request is currently under review and will be considered for inclusion in a period between Boost releases when priority moves from the Boost website.

Boost Website

Among the many support projects for the new Boost website, I’ve been helping the most on cppalliance/site-docs, which includes the Boost website documentation as an Antora project. Its components represent the “User Guide”, “Contributor Guide”, and “Formal Review” sections of the website.

Since the inception of the project, I’ve been overseeing and reviewing all the work done by the other contributors to the project.

In general, I continue to be responsible for:

  • reviewing and merging all pull requests to the project;
  • setting up and maintaining CI for the project;
  • coordinating with the website project on content uploaded to AWS buckets;
  • build scripts to be reused by the release tools and previews;
  • writing sections of the documentation that require technical knowledge;
  • developing custom Boost/Antora extensions, such as the Boost Macro extension;
  • maintaining the Antora toolchain and templates; and
  • adjusted Boost libraries to match formats expected by the website.

C++ Github Actions

C++ Github Actions is a project I created and have been maintaining since Q3. It is a collection of compasable, independent, and reusable Github Actions for any C++ project that needs to be tested on a variety of compilers and environments.

Both MrDocs are Boost.URL are currently using these actions in their CI. Boost.Http is now also using these actions in its CI, which gave us the opportunity to get more feedback and improve the actions.

The project includes actions to:

  • Generate a Github Actions Matrix for C++ projects;
  • Setup C++ compilers;
  • Install and setup packages;
  • Clone Boost modules;
  • Run complete CMake and b2 workflows;
  • Generate changelogs from conventional commits;
  • Generate summaries; and
  • Generate time-trace reports and flame graphs

In particular, a number of new features have been added to the project in Q4.

  • The matrix has been adapted to include multiple extra flags and values over time.
  • Actions that generate summaries included improvements and new sections.
  • Actions can now identify many new types of warnings that should be emitted.
  • CMake and B2 workflows included more options and features.
  • The matrix new support composite factors, combinatorial factors, and custom containers.
  • Documentation has been improved to also use the collector Antora extension.

Besides new features, most work went into fixing issues that were revealed by testing the actions in new environments. About ~50 bugs with various levels of severity have been fixed in Q4.

All Posts by This Author