New Doxybook/Jekyll-based GitHub Pages documentation infrastructure

[brycelelbach]

This PR introduces a new documentation infrastructure. It generates Doxygen XML output, and then uses the Doxybook2 framework to generate GitHub Flavored Markdown. That GitHub Flavored Markdown is rendered using the Jekyll just-the-docs theme.

The final product is documentation in the style of the C++ Standard and cppreference that can be deployed to GitHub Pages. For each class or Doxygen group, there is a code synopsis of all entities, followed by a section that contains detailed descriptions of them. Users can browse the docs using the sidebar or with just-the-docs powerful builtin search mechanism.

There are two scripts that can be used to locally build and host the docs:

• docs/generate_markdown.bash: This runs Doxygen and then Doxybook to generate the Markdown for the API docs.
• docs/serve_jekyll_locally.bash: This will start a local Jekyll server that will host the docs. You need to run docs/generate_markdown.bash first. Jekyll will build the HTML site when it starts, which takes a few minutes.

To build locally, you need to install Doxygen, Ruby (Debian package: ruby-dev), and Bundler (Debian package: bundler), which you should be able to do through your system's package manager.

You'll also need to build Doxybook from source, which is pretty easy to do. You'll need vcpkg to install Doxybook's dependencies - note that you'll need to specify --head when installing the inja dependency to ensure you get the correct version:

vcpkg install argagg catch2 fmt dirent fmt nlohmann-json rang
vcpkg install --head inja

Note that the above command install inja may fail within the NVIDIA VPN due to GitHub API rate limits (see microsoft/vcpkg#19177). As an alternative, you can just grab and build inja, and then add the inja build directory to your CMAKE_PREFIX_PATH when building Doxybook.

Automated builds and deploy of the docs to GitHub pages are in place. The rendered docs from the tip of this branch can be seen at https://nvidia.github.io/thrust

[alliepiper]

I didn't finish reviewing yet, but I had some issues building the docs.

Minor issue: The script names in the PR's comment are slightly different from what's in the patch (generate vs. build, etc).

Major issue: building the docs fails with:

Exception at Renderer.cpp:362 Render template 'kind_nonclass' error [inja.exception.render_error] (at 4:33) variable 'child.strong' not found

[brycelelbach]

Major issue: building the docs fails with:

Exception at Renderer.cpp:362 Render template 'kind_nonclass' error [inja.exception.render_error] (at 4:33) variable 'child.strong' not found

The issue is in this code in the template:

{%- if child.kind == "enum" and child.strong %} Class{%- endif -%}

That code assumes that inja (the template engine for doxybook) supports short circuiting of boolean logic operators, which was only added in the latest release at my request. My guess is that the default version of inja in vcpkg isn't new enough. I believe this can be fixed by getting the "head" version from vcpkg.

[ras0219-msft]

With microsoft/vcpkg#19208 (now merged), --head should no longer be needed for inja which should workaround the github api rate limit issue

[alliepiper]

Looks like the code changes in this PR were not tested and broke builds. Fixes are in #1606.

All code changes need to be run through gpuCI/DVS before merging.