Skip to content
This repository has been archived by the owner on Mar 21, 2024. It is now read-only.

New Doxybook/Jekyll-based GitHub Pages documentation infrastructure #1475

Merged
merged 57 commits into from
Jan 24, 2022

Conversation

brycelelbach
Copy link
Collaborator

@brycelelbach brycelelbach commented Jul 2, 2021

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

@brycelelbach brycelelbach added type: enhancement New feature or request. P0: must have Absolutely necessary. Critical issue, major blocker, etc. labels Jul 2, 2021
@alliepiper alliepiper added this to the 1.14.0 milestone Jul 2, 2021
Copy link
Collaborator

@alliepiper alliepiper left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

.gitignore Outdated Show resolved Hide resolved
docs/.gitignore Outdated Show resolved Hide resolved
docs/contributing.md Outdated Show resolved Hide resolved
docs/generate_markdown.bash Outdated Show resolved Hide resolved
thrust/async/copy.h Outdated Show resolved Hide resolved
@brycelelbach
Copy link
Collaborator Author

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.

@brycelelbach brycelelbach force-pushed the feature/new-docs branch 14 times, most recently from 8d23b5c to add5afc Compare July 28, 2021 03:57
@ras0219-msft
Copy link

ras0219-msft commented Jul 28, 2021

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

docs/doxybook_config.json Outdated Show resolved Hide resolved
… with

Doxygen so that things actually show up in namespaces.
… of the

incorrect "baseURL" to Doxybook via `--config-data`, so that local builds
actually use the correct path prefix.
…g the

newly exposed `qualifiedname` metadata that I've modified Doxygen and Doxybook
to output. This fixes a rendering bug with the section titles of template class
member functions where `::>::` would erronously appear because the now-unneeded
`extractQualifiedNameFromFunctionDefinition` didn't work correctly.
* Mention that C++11 is deprecated in the requirements section.
* Instead of specifying a specific version of NVCC and NVC++, say that the
  latest version is required.
* Remove Android and QNX from the list of supported platforms.
* Fix a copy/paste error that said "libcu++" instead of "Thrust and CUB".
* thrust/system/detail/sequential/sort.inl: Fix typo in copyright date.
* thrust/system_error.h: Remove extraneous space and fix formatting in Doxygen
  comment for namespace `thrust::system`.
…dering

macros: it doesn't have the parameters for function-like macros and doesn't
have line breaks for multi-line macro definitions.
…in groups

to use the same anchor escaping that Doxybook links to those sections expect.
This fixes broken links to many things.
…d from"

into each synopsis template so that newlines are inserted in the right place.
… the

underlying steps fails, so that errors are correctly reported by the GitHub
action that runs it.
`build_docs` and unify the baseurl local builds and deployed GitHub Pages
builds.
…Hub Pages

so that the right versions of Doxybook and Doxygen are used.
@brycelelbach brycelelbach merged commit 015ca7a into main Jan 24, 2022
@brycelelbach brycelelbach deleted the feature/new-docs branch January 24, 2022 21:17
alliepiper added a commit to alliepiper/thrust that referenced this pull request Jan 25, 2022
@alliepiper
Copy link
Collaborator

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.

alliepiper added a commit to alliepiper/thrust that referenced this pull request Jan 25, 2022
This reverts the changes merged from NVIDIA#1475 so they can be retested.
alliepiper added a commit that referenced this pull request Jan 25, 2022
brycelelbach pushed a commit that referenced this pull request Feb 1, 2022
brycelelbach pushed a commit that referenced this pull request Feb 1, 2022
@alliepiper alliepiper removed this from the 1.16.0 milestone Feb 7, 2022
brycelelbach pushed a commit that referenced this pull request Feb 10, 2022
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Labels
P0: must have Absolutely necessary. Critical issue, major blocker, etc. type: enhancement New feature or request.
Projects
None yet
Development

Successfully merging this pull request may close these issues.

4 participants