Setup documentation and corresponding github action (#1118)

* Make top level docs for CCCL.

* Fix image paths

* Add Thrust docs build and fix any issues

* Add CUB docs build

* Fix PTX docs interpretting liquid syntax

* Fixup libcudacxx baseurl in docs

* Fixup cub permission in gen_docs.bash

* Fixup thrust docs script permissions

* Fix favicon in libcudacxx

* Document `$TAG`.

* Document scripts better.

.github/workflows/build-docs.yml

@@ -0,0 +1,83 @@
+name: Deploy CCCL pages
+
+on:
+  # Runs on pushes targeting the default branch
+  push:
+    branches: ["main"]
+
+  # Allows you to run this workflow manually from the Actions tab
+  workflow_dispatch:
+
+# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
+# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+jobs:
+  # Build job
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v3
+      - name: Setup Pages
+        uses: actions/configure-pages@v3
+
+      # Build helper image for Thrust/CUB
+      - name: Build helper image
+        run: |
+          bash ./docs/make_env.bash "cccl:docs"
+
+      # Build top level docs for CCCL
+      - name: Build landing page
+        uses: actions/jekyll-build-pages@v1
+        with:
+          source: ./docs/jekyll
+          destination: ./_site
+
+      # CUB
+      - name: Build CUB docs
+        run: |
+          bash ./docs/build_docs.bash "cccl:docs" /cccl/cub/docs/gen_docs.bash
+          sudo mkdir -p ./_site/cub
+          sudo cp -rf ./cub/docs/_build/docs/CUB/latest/* ./_site/cub
+
+      # Libcudacxx
+      - name: Build libcudacxx docs
+        uses: actions/jekyll-build-pages@v1
+        with:
+          source: ./libcudacxx/docs
+          destination: ./_site/libcudacxx
+
+      # Thrust
+      - name: Build Thrust markdown in Docker
+        run: bash ./docs/build_docs.bash "cccl:docs" /cccl/thrust/docs/build_docs_locally.bash
+
+      - name: Build Thrust docs
+        uses: actions/jekyll-build-pages@v1
+        with:
+          source: ./thrust/build_docs/github_pages
+          destination: ./_site/thrust
+
+      # Upload build artifacts
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v2
+
+  # Deployment job
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    needs: build
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v2

cub/docs/gen_docs.bash

@@ -0,0 +1,30 @@
+#!/usr/bin/env bash
+
+## This script just wraps launching a docs build within a container
+## Tag is passed on as the first argument ${1}
+
+set -e
+
+SCRIPT_PATH=$(cd $(dirname ${0}); pwd -P)
+
+cd $SCRIPT_PATH
+
+## Clean image directory, without this any artifacts will prevent fetching
+rm -rf img
+mkdir -p img
+
+if [ ! -n "$(find img -name '*.png')" ]; then
+    wget -q https://docs.nvidia.com/cuda/_static/Logo_and_CUDA.png -O img/logo.png
+
+    # Parse files and collects unique names ending with .png
+    imgs=( $(grep -R -o -h '[[:alpha:][:digit:]_]*.png' ../cub | uniq) )
+    imgs+=( "cub_overview.png" "nested_composition.png" "tile.png" "blocked.png" "striped.png" )
+
+    for img in "${imgs[@]}"
+    do
+        echo ${img}
+        wget -q https://nvlabs.github.io/cub/${img} -O img/${img} || echo "!!! Failed to fetch $img"
+    done
+fi
+
+./repo.sh docs || echo "!!! There were errors while generating"

cub/docs/repo.toml

@@ -102,7 +102,7 @@ doxygen_predefined = [
     "CUB_IGNORE_DEPRECATED_CPP_DIALECT"
 ]
 
-# make sure to use ./fetch_imgs.sh 
+# make sure to use ./fetch_imgs.sh
 doxygen_conf_extra = """
   IMAGE_PATH             = ${config_root}/img
   DOXYFILE_ENCODING      = UTF-8

docs/Dockerfile

@@ -0,0 +1,18 @@
+FROM ubuntu:22.04
+
+SHELL [ "/usr/bin/env", "/bin/bash", "-c" ]
+
+ENV APT_KEY_DONT_WARN_ON_DANGEROUS_USAGE=1
+
+RUN apt-get -y -qq update; \
+    apt-get -y -qq upgrade; \
+    apt-get -y -qq install doxygen unzip wget
+
+RUN mkdir -p /opt/doxybook2; \
+    cd /opt/doxybook2; \
+    wget -q -O doxybook2.zip "https://github.com/matusnovak/doxybook2/releases/download/v1.5.0/doxybook2-linux-amd64-v1.5.0.zip"; \
+    unzip doxybook2.zip
+
+ENV PATH "$PATH:/opt/doxybook2/bin"
+
+SHELL [ "/bin/bash" ]

docs/build_docs.bash

@@ -0,0 +1,21 @@
+#!/usr/bin/env sh
+
+## This script just wraps launching a docs build within a container
+## Tag is passed on as the first argument ${1}
+
+set -ex
+
+SCRIPT_PATH=$(cd $(dirname ${0}); pwd -P)
+cd $SCRIPT_PATH
+
+CCCL_ROOT=$(realpath $SCRIPT_PATH/..)
+
+TAG=${1}
+shift
+
+(
+    docker run --rm \
+        --mount type=bind,src=${CCCL_ROOT},dst=/cccl \
+        $TAG \
+            bash -c "$@"
+)

docs/jekyll/_config.yaml

@@ -0,0 +1,30 @@
+title: CUDA C++ Core Libraries
+
+repository: nvidia/cccl
+
+remote_theme: pmarsceill/just-the-docs
+
+color_scheme: nvidia
+logo: /images/nvidia_logo.png
+
+search_enabled: true
+search.heading_level: 4
+
+# just-the-docs ignores these filenames by default.
+include: [ "contributing.md", "code_of_conduct.md" ]
+
+plugins_dir:
+  - jekyll-remote-theme
+  - jekyll-optional-front-matter # GitHub Pages.
+  - jekyll-default-layout        # GitHub Pages.
+  - jekyll-titles-from-headings  # GitHub Pages.
+  - jekyll-relative-links        # GitHub Pages.
+
+defaults:
+  -
+    scope:
+      path: index.md
+    values:
+      title: index
+      nav_order: 0
+      permalink: /

docs/jekyll/_sass/color_schemes/nvidia.scss

@@ -0,0 +1,125 @@
+$body-line-height: 1.4;
+$content-line-height: 1.4;
+.highlight { line-height: 1.0 !important; }
+
+/* h1 size. We make this smaller so the README title fits on one line. */
+$font-size-9: 30px;
+
+/* Inline code. */
+code,
+code.highlighter-rouge
+{ font-size: 0.85em !important; }
+
+/* Code blocks. */
+pre.highlight code
+{ font-size: 0.9em !important; }
+
+$nav-width: 300px;
+$content-width: 1000px;
+
+$body-background-color: $grey-dk-300;
+$sidebar-color: $grey-dk-300;
+$border-color: $grey-dk-200;
+
+$body-text-color: $grey-lt-300;
+$body-heading-color: $grey-lt-000;
+$nav-child-link-color: $grey-dk-000;
+$search-result-preview-color: $grey-dk-000;
+
+$link-color: #76b900;
+$btn-primary-color: #76b900;
+$base-button-color: $grey-dk-250;
+
+$code-background-color: $grey-dk-250;
+$search-background-color: $grey-dk-250;
+$table-background-color: $grey-dk-250;
+$feedback-color: darken($sidebar-color, 3%);
+
+div.highlighter-rouge,
+pre.highlight code
+{ background-color: #111 !important; }
+
+.highlight span.err { color: #ff0000; font-weight: bold; } /* Error */
+
+.highlight span.ow, /* Operator.Word */
+.highlight span.k,  /* Keyword */
+.highlight span.kc, /* Keyword.Constant */
+.highlight span.kd, /* Keyword.Declaration */
+.highlight span.kp, /* Keyword.Pseudo */
+.highlight span.kr, /* Keyword.Reserved */
+.highlight span.bp, /* Name.Builtin.Pseudo */
+.highlight span.vc, /* Name.Variable.Class */
+.highlight span.vg, /* Name.Variable.Global */
+.highlight span.vi  /* Name.Variable.Instance */
+{ color: #76b900; font-weight: bold; }
+
+.highlight span.n,  /* Name */
+.highlight span.h,  /* Name */
+.highlight span.na, /* Name.Attribute */
+.highlight span.nb, /* Name.Builtin */
+.highlight span.nc, /* Name.Class */
+.highlight span.no, /* Name.Constant */
+.highlight span.nd, /* Name.Decorator */
+.highlight span.ni, /* Name.Entity */
+.highlight span.ne, /* Name.Exception */
+.highlight span.nf, /* Name.Function */
+.highlight span.nl, /* Name.Label */
+.highlight span.nn, /* Name.Namespace */
+.highlight span.nx, /* Name.Other */
+.highlight span.py, /* Name.Property */
+.highlight span.nt, /* Name.Tag */
+.highlight span.nv, /* Name.Variable */
+.highlight span.kt  /* Keyword.Type */
+{ color: $grey-lt-300 }
+
+.highlight span.c,  /* Comment */
+.highlight span.cm, /* Comment.Multiline */
+.highlight span.c1, /* Comment.Single */
+.highlight span.cs  /* Comment.Special */
+{ color: #009966; font-style: italic }
+
+.highlight span.cp  /* Preprocessor */
+.highlight span.kn, /* Keyword.Namespace */
+{ color: $grey-dk-000 }
+
+.highlight span.o, /* Operator */
+.highlight span.p  /* Punctuation */
+{ color: #00ff00 }
+
+.highlight span.ge { font-style: italic } /* Generic.Emph */
+
+.highlight span.gs { font-weight: bold } /* Generic.Strong */
+
+.highlight span.l,  /* Literal */
+.highlight span.ld, /* Literal.Date */
+.highlight span.m,  /* Literal.Number */
+.highlight span.mf, /* Literal.Number.Float */
+.highlight span.mh, /* Literal.Number.Hex */
+.highlight span.mi, /* Literal.Number.Integer */
+.highlight span.mo, /* Literal.Number.Oct */
+.highlight span.il, /* Literal.Number.Integer.Long */
+.highlight span.s,  /* Literal.String */
+.highlight span.sb, /* Literal.String.Backtick */
+.highlight span.sc, /* Literal.String.Char */
+.highlight span.sd, /* Literal.String.Doc */
+.highlight span.s2, /* Literal.String.Double */
+.highlight span.se, /* Literal.String.Escape */
+.highlight span.sh, /* Literal.String.Heredoc */
+.highlight span.si, /* Literal.String.Interpol */
+.highlight span.sx, /* Literal.String.Other */
+.highlight span.sr, /* Literal.String.Regex */
+.highlight span.s1, /* Literal.String.Single */
+.highlight span.ss  /* Literal.String.Symbol */
+{ color: #119911 }
+
+.highlight span.w { color: #00cc00 } /* Text.Whitespace */
+
+.highlight span.gh, /* Generic.Heading */
+.highlight span.gp, /* Generic.Prompt */
+.highlight span.gu  /* Generic.Subheading */
+{ color: #00ff00; font-weight: bold }
+
+.highlight span.gd { color: #ff0000 } /* Generic.Deleted */
+.highlight span.gi { color: #00ff00 } /* Generic.Inserted */
+
+.search-input { color: $body-text-color; }

docs/jekyll/index.md

@@ -0,0 +1,5 @@
+# CUDA C++ Core Libraries (CCCL)
+
+- [Thrust](thrust)
+- [CUB](cub)
+- [libcudacxx](libcudacxx)

docs/make_env.bash

@@ -0,0 +1,13 @@
+#!/usr/bin/env sh
+
+## This script just wraps launching a docs build within a container
+## Tag is passed on as the first argument ${1}
+
+set -ex
+
+SCRIPT_PATH=$(cd $(dirname ${0}); pwd -P)
+cd $SCRIPT_PATH
+
+TAG=${1}
+
+docker build -f ./Dockerfile -t $TAG .

docs/readme.md

@@ -0,0 +1,23 @@
+# Building docs
+
+Most docs can be *prepared* locally, but the build process is partially invested in the github workflows. This script accepts a tag name and runs a given script inside the container. This takes care of dependencies and system config for the user.
+
+## First steps
+
+Prepare docker container for local builds. `$TAG` is the image name you want to use. CCCL uses `cccl:docs` for its local tag name in the action.
+
+```bash
+make_env.bash $TAG
+```
+
+## Build Thrust
+
+```bash
+build_docs.bash $TAG /cccl/thrust/docs/build_docs_locally.bash
+```
+
+## Build CUB
+
+```bash
+build_docs.bash $TAG /cccl/cub/docs/gen_docs.bash
+```