Docs: Restructure new Doxybook/Jekyll framework to build out of tree in

`build_docs` and unify the baseurl local builds and deployed GitHub Pages
builds.

.github/workflows/generate-github-pages.yml → .github/workflows/deploy-documentation-github-pages.yml

@@ -1,24 +1,24 @@
-name: Generate GitHub Pages
+name: Deploy Documentation GitHub Pages
 
 on:
   push:
     branches:
       - feature/new-docs
 
 jobs:
-  generate-github-pages:
+  deploy-documentation-github-pages:
     runs-on: ubuntu-latest
     container: gpuci/cccl:cuda11.3.1-devel-ubuntu20.04-gcc9
     steps:
       - name: Checkout repository
         uses: actions/checkout@v2
       - name: Generate documentation markdown
-        run: ./docs/generate_markdown.bash
+        run: ./docs/generate_markdown.bash --clean
       - name: Deploy generated documentation markdown to gh-pages branch
         uses: peaceiris/actions-gh-pages@v3
-        if: github.ref == 'refs/heads/feature/new-docs'
+        if: github.ref == 'refs/heads/main' || github.ref == 'refs/heads/feature/new-docs'
         with:
           github_token: ${{ secrets.GITHUB_TOKEN }}
-          publish_dir: ./docs
+          publish_dir: ./build_docs/github_pages
           enable_jekyll: true
-          commit_message: "Deploy Docs: ${{ github.event.head_commit.message }}"
+          commit_message: "Deploy Documentation: ${{ github.event.head_commit.message }}"

.gitignore

@@ -1,11 +1 @@
 discrete_voronoi.pgm
-docs/html/
-docs/api/
-docs/overview.md
-docs/contributing/code_of_conduct.md
-docs/releases/changelog.md
-docs/Gemfile.lock
-docs/_site
-docs/.bundle
-docs/.sass-cache
-docs/.jekyll-metadata

docs/doxybook_config.json → docs/doxybook/config.json

@@ -1,5 +1,5 @@
 {
-  "baseUrl": "/thrust/api/",
+  "baseUrl": "{{ site.baseurl }}/api/",
   "copyImages": true,
   "fileExt": "md",
   "filesFilter": [],

docs/doxygen_config.dox → docs/doxygen/config.dox

@@ -1149,7 +1149,7 @@ GENERATE_HTML          = NO
 # The default directory is: html.
 # This tag requires that the tag GENERATE_HTML is set to YES.
 
-HTML_OUTPUT            = build_doxygen_html
+HTML_OUTPUT            = build_docs/doxygen/html
 
 # The HTML_FILE_EXTENSION tag can be used to specify the file extension for each
 # generated HTML page (for example: .htm, .php, .asp).
@@ -2058,7 +2058,7 @@ GENERATE_XML           = YES
 # The default directory is: xml.
 # This tag requires that the tag GENERATE_XML is set to YES.
 
-XML_OUTPUT             = build_doxygen_xml
+XML_OUTPUT             = build_docs/doxygen/xml
 
 # If the XML_PROGRAMLISTING tag is set to YES, doxygen will dump the program
 # listings (including syntax highlighting and cross-referencing information) to

docs/generate_markdown.bash

@@ -27,74 +27,80 @@ function usage {
   echo "-h, -help, --help"
   echo "  Print this message."
   echo
-  echo "-l, --local"
-  echo "  Generate markdown suitable for a locally run Jekyll server instead of "
-  echo "  the production GitHub pages environment."
+  echo "-c, --clean"
+  echo "  Delete the all existing build artifacts before generating the "
+  echo "  markdown."
 
   exit -3
 }
 
 LOCAL=0
+CLEAN=0
 
 while test ${#} != 0
 do
   case "${1}" in
   -h) ;&
   -help) ;&
   --help) usage ;;
-  -l) ;&
-  --local) LOCAL=1 ;;
+  -c) ;&
+  --clean) CLEAN=1 ;;
   esac
   shift
 done
 
 SCRIPT_PATH=$(cd $(dirname ${0}); pwd -P)
 
-cd ${SCRIPT_PATH}/..
-
-rm -rf build_doxygen_xml
-rm -rf docs/api
-rm -f docs/overview.md
-rm -f docs/contributing/code_of_conduct.md
-rm -f docs/releases/changelog.md
-
-mkdir -p docs/api
-mkdir -p docs/contributing
-mkdir -p docs/releases
-
-# We need to copy these files into the `docs/` root because Jekyll doesn't let
-# you include content outside of its root.
-cp README.md docs/overview.md
-cp CODE_OF_CONDUCT.md docs/contributing/code_of_conduct.md
-cp CHANGELOG.md docs/releases/changelog.md
-
-doxygen docs/doxygen_config.dox
-
-# When we're deploying to production on GitHub Pages, the root is
-# `nvidia.github.io/thrust`. When we're building locally, the root is normally
-# just `localhost`.
-if [[ "${LOCAL}" == 1 ]]; then
-  BASE_URL='{"baseUrl": "/api/"}'
-else
-  BASE_URL='{"baseUrl": "/thrust/api/"}'
+REPO_PATH=${SCRIPT_PATH}/..
+
+BUILD_DOCS_PATH=build_docs
+BUILD_DOXYGEN_PATH=${BUILD_DOCS_PATH}/doxygen
+BUILD_GITHUB_PAGES_PATH=${BUILD_DOCS_PATH}/github_pages
+
+cd ${REPO_PATH}
+
+if [[ "${CLEAN}" == 1 ]]; then
+  rm -rf ${BUILD_DOXYGEN_PATH}
+  rm -rf ${BUILD_GITHUB_PAGES_PATH}
 fi
 
-doxybook2 -d -i build_doxygen_xml -o docs/api -c docs/doxybook_config.json --config-data "${BASE_URL}" -t docs/doxybook_templates
+mkdir -p ${BUILD_DOXYGEN_PATH}/xml
+mkdir -p ${BUILD_GITHUB_PAGES_PATH}
+mkdir -p ${BUILD_GITHUB_PAGES_PATH}/api
+mkdir -p ${BUILD_GITHUB_PAGES_PATH}/contributing
+mkdir -p ${BUILD_GITHUB_PAGES_PATH}/releases
+
+# Copy all the documentation sources and Jekyll configuration into
+# `{BUILD_GITHUB_PAGES_PATH}`.
+cp -ur docs/github_pages/* ${BUILD_GITHUB_PAGES_PATH}/
+cp README.md               ${BUILD_GITHUB_PAGES_PATH}/overview.md
+cp CODE_OF_CONDUCT.md      ${BUILD_GITHUB_PAGES_PATH}/contributing/code_of_conduct.md
+cp CHANGELOG.md            ${BUILD_GITHUB_PAGES_PATH}/releases/changelog.md
+
+doxygen docs/doxygen/config.dox
+
+# `--debug-templates` will cause JSON output to be generated, which is useful
+# for debugging.
+doxybook2 --config docs/doxybook/config.json  \
+          --templates docs/doxybook/templates \
+          --debug-templates                   \
+          --input ${BUILD_DOXYGEN_PATH}/xml   \
+          --output ${BUILD_GITHUB_PAGES_PATH}/api
 
 # Doxygen and Doxybook don't give us a way to disable all the things we'd like,
 # so it's important to purge Doxybook Markdown output that we don't need:
 # 0) We want our Jekyll build to be as fast as possible and avoid wasting time
 #    on stuff we don't need.
 # 1) We don't want content that we don't plan to use to either show up on the
 #    site index or appear in search results.
-rm -rf docs/api/files
-rm -rf docs/api/index_files.md
-rm -rf docs/api/pages
-rm -rf docs/api/index_pages.md
-rm -rf docs/api/examples
-rm -rf docs/api/index_examples.md
-rm -rf docs/api/images
-rm -rf docs/api/index_namespaces.md
-rm -rf docs/api/index_groups.md
-rm -rf docs/api/index_classes.md
+rm -rf ${BUILD_GITHUB_PAGES_PATH}/api/files
+rm -rf ${BUILD_GITHUB_PAGES_PATH}/api/index_files.md
+rm -rf ${BUILD_GITHUB_PAGES_PATH}/api/pages
+rm -rf ${BUILD_GITHUB_PAGES_PATH}/api/index_pages.md
+rm -rf ${BUILD_GITHUB_PAGES_PATH}/api/examples
+rm -rf ${BUILD_GITHUB_PAGES_PATH}/api/index_examples.md
+rm -rf ${BUILD_GITHUB_PAGES_PATH}/api/images
+rm -rf ${BUILD_GITHUB_PAGES_PATH}/api/index_namespaces.md
+rm -rf ${BUILD_GITHUB_PAGES_PATH}/api/index_groups.md
+rm -rf ${BUILD_GITHUB_PAGES_PATH}/api/index_classes.md
 

docs/serve_docs_locally.bash

@@ -18,7 +18,18 @@
 
 SCRIPT_PATH=$(cd $(dirname ${0}); pwd -P)
 
-cd ${SCRIPT_PATH}/..
+REPO_PATH=${SCRIPT_PATH}/..
+
+BUILD_DOCS_PATH=build_docs
+BUILD_GITHUB_PAGES_PATH=${BUILD_DOCS_PATH}/github_pages
+
+cd ${REPO_PATH}/${BUILD_GITHUB_PAGES_PATH}
 
 bundle install
-bundle exec jekyll serve --incremental --profile --verbose
+bundle exec jekyll serve \
+  --verbose              \
+  --incremental          \
+  --profile              \
+  --baseurl "/thrust"    \
+  ${@}
+