From b4ec87ff852da47672f1ceed63455a46ed6d38ba Mon Sep 17 00:00:00 2001 From: Jon Leech Date: Fri, 3 May 2024 03:22:13 -0700 Subject: [PATCH] Refactor all build targets into top-level Makefile And rename new 'features' component to match Vulkan-Docs. --- Makefile | 91 +++++++++++++++++++++++++++++++++++ docs-site/Makefile | 57 ---------------------- docs-site/antora-playbook.yml | 2 +- 3 files changed, 92 insertions(+), 58 deletions(-) create mode 100644 Makefile delete mode 100644 docs-site/Makefile diff --git a/Makefile b/Makefile new file mode 100644 index 00000000..cc3cc6ac --- /dev/null +++ b/Makefile @@ -0,0 +1,91 @@ +# Copyright 2023-2024 The Khronos Group Inc. +# SPDX-License-Identifier: Apache-2.0 + +# Makefile for Vulkan Documentation Project +# This exists because we cannot just run the Antora playbook on the +# repository sources, since we are not yet using Antora Collector to do +# all the preprocessing on the repositories required to make their +# contents compatible with Antora. + +# The Antora UI and components each exist in separate git repositories. +# They must be present as subdirectories, but are *not* git submodules. +# They could be separate repository clones, or links elsewhere. + +# Targets: +# 'init' - updates whatever the current branch is in each repository, +# then installs npm dependencies. +# This need only be done when switching branches. +# This Makefile itself does no branch selection. +# 'build-ui' - builds the Antora UI package. +# 'prep-sources' - prepare each repository's files for Antora. +# This has four subtargets for the separate repos: +# 'prep-docs' - Vulkan-Docs (specification and feature description +# components +# 'prep-guide' - Vulkan Guide +# 'prep-samples' - Vulkan Samples +# 'prep-tutorials' - Vulkan Tutorials +# 'build-site' - builds the Antora site after prep-sources. +# 'clean' - cleans the Antora site + +# UI and component repositories which must exist as subdirectories to build +REPONAMES = antora-ui-khronos Vulkan-Guide Vulkan-Samples Vulkan-Tutorial Vulkan-Docs + +# Directories (mostly repos) with their own npm infrastructure +DIRSWITHNODE = antora-ui-khronos docs-site Vulkan-Docs + +# Initialize subdirectory repositories and modules +# There are no longer any modules +init: subrepos + for repo in $(REPONAMES) ; do \ + (cd $$repo && git pull) ; \ + done + # Install various node modules + # Don't clean the cache (see 'npm cache clean' output for more) + # npm cache clean --force + for dir in $(DIRSWITHNODE) ; do \ + (cd $$dir && npm install) ; \ + done + +subrepos: $(REPONAMES) + for repo in $(REPONAMES) ; do \ + test -d $$repo || git clone git@github.com:KhronosGroup/$$repo.git ; \ + done + +# Build UI bundle +build-ui: + cd antora-ui-khronos && \ + npx update-browserslist-db@latest && \ + ./node_modules/gulp/bin/gulp.js --version && \ + ./node_modules/gulp/bin/gulp.js bundle + # Creates antora-ui-khronos/build/ui-bundle.zip + cp antora-ui-khronos/build/ui-bundle.zip docs-site + +# Prepare component antora sources +prep-sources: prep-docs prep-guide prep-samples prep-tutorial + +# Prepare Vulkan-Docs +GENPATH = Vulkan-Docs/antora/spec/modules/ROOT/partials/gen +prep-docs: + make -C Vulkan-Docs -f antora/Makefile clean setup + cp $(GENPATH)/apimap.cjs \ + $(GENPATH)/pageMap.cjs \ + Vulkan-Docs/antora/spec/xrefMap.cjs \ + docs-site/js/ + +prep-guide: + make -C Vulkan-Guide -f antora/Makefile clean setup + +prep-samples: + cd Vulkan-Samples && cmake -H"." -B"build/unix" -DVKB_GENERATE_ANTORA_SITE=ON + +prep-tutorial: + make -C Vulkan-Tutorial/antora setup_tutorial + +# Build Antora site +build-site: + cd docs-site && npx antora antora-playbook.yml --stacktrace + +# Clean Antora site (but not prepared component sources) +clean: + rm -rf docs-site/build + diff --git a/docs-site/Makefile b/docs-site/Makefile deleted file mode 100644 index c8c7cb0c..00000000 --- a/docs-site/Makefile +++ /dev/null @@ -1,57 +0,0 @@ -# Copyright 2023-2024 The Khronos Group Inc. -# SPDX-License-Identifier: Apache-2.0 - -# Makefile for Vulkan Documentation Project -# This exists because we cannot just run the Antora playbook on the -# repository sources, since we are not yet using Antora Collector to do -# all the preprocessing on the repositories required to make their -# documents compatible with Antora. - -# There are two targets: -# -# prepare_components (prepare_guide, prepare_spec) - preprocess the -# local clones and copy required JavaScript files used by custom -# extensions into the playbook repository. This takes a relatively long -# time and is broken out as a separate step. It should be done whenever -# the branch content is updated. -# -# build_site - run the Antora playbook and generate the site. -# Requires prepare_components to have run. - -# GUIDEREPO and SPECREPO contain absolute paths to local clones of the -# Vulkan-Guide and Vulkan-Docs repositories, respectively. -# They must match the paths hardwired into antora-playbook.yml. - -GUIDEREPO = ../Vulkan-Guide -SPECREPO = ../Vulkan-Docs - -# GUIDEBRANCH and SPECBRANCH are the branches in those local clones -# from which to build. - -#GUIDEBRANCH = antora -#SPECBRANCH = github-main - -GUIDEBRANCH = main -SPECBRANCH = main -#SPECBRANCH = tilde-blocks-to-dashes - -prepare_components: prepare_guide prepare_spec - -prepare_guide: - cd $(GUIDEREPO) && \ - git checkout $(GUIDEBRANCH) && \ - make -f antora/Makefile clean setup - -GENPATH = $(SPECREPO)/antora/spec/modules/ROOT/partials/gen -prepare_spec: - cd $(SPECREPO) && \ - git checkout $(SPECBRANCH) && \ - make -f antora/Makefile clean setup - cp $(GENPATH)/apimap.cjs $(GENPATH)/pageMap.cjs js/ - cp $(SPECREPO)/antora/spec/xrefMap.cjs js/ - -build_site: clean - npx antora antora-playbook.yml $(BUILDARGS) - -clean: - rm -rf build diff --git a/docs-site/antora-playbook.yml b/docs-site/antora-playbook.yml index 22e37584..adde65bf 100644 --- a/docs-site/antora-playbook.yml +++ b/docs-site/antora-playbook.yml @@ -13,7 +13,7 @@ content: start_path: antora - url: ../Vulkan-Docs branches: HEAD - start_paths: antora/spec, antora/proposals + start_paths: antora/spec, antora/features - url: ../Vulkan-Samples branches: HEAD start_path: antora