This directory contains a tool to convert Doxygen XML into DocFX YAML files.
This tool is used to generate the google-cloud-cpp reference documentation
when hosted at cloud.google.com.
This is not a general-purpose tool. It is not expected to work for other C++
projects. This tool is only used as part of the documentation pipeline for
google-cloud-cpp. As such, it is only tested on a limited number of platforms.
This assumes you are building with CMake. More details on CMake configuration in the How-to Guide.
cd google-cloud-cpp
ci/cloudbuild/build.sh -t publish-docs-pr
cd google-cloud-cpp
git clone https://github.com/googleapis/doc-pipeline.git $HOME/doc-pipeline
cd google-cloud-cpp
git clone https://github.com/microsoft/vcpkg.git $HOME/vcpkg
cd google-cloud-cpp
cmake -GNinja -S . -B build-out/.docfx -DGOOGLE_CLOUD_CPP_INTERNAL_DOCFX=ON \
--toolchain $HOME/vcpkg/scripts/buildsystems/vcpkg.cmake
PUBLISH=$PWD/build-out/fedora-latest-publish-docs/publish-docs/__default__/cmake-out/google/cloud
cmake --build build-out/.docfx --target docfx/all \
&& rm -f $HOME/doc-pipeline/testdata/cpp/* \
&& env -C $HOME/doc-pipeline/testdata/cpp $PWD/build-out/.docfx/docfx/doxygen2docfx $PUBLISH/xml/cloud.doxygen.xml cloud 2.9.0
env -C $HOME/doc-pipeline \
INPUT=testdata/cpp \
TRAMPOLINE_BUILD_FILE=./generate.sh \
TRAMPOLINE_IMAGE=gcr.io/cloud-devrel-kokoro-resources/docfx \
TRAMPOLINE_DOCKERFILE=docfx/Dockerfile ci/trampoline_v2.sh
The output is HTML with templates and embedded markdown:
ls -l $HOME/doc-pipeline/site
less $HOME/doc-pipeline/site/namespacegoogle.html
less $HOME/doc-pipeline/site/indexpage.html
Run the previous steps and then:
cp $HOME/doc-pipeline/site/xrefmap.yml build-out
cmake --build .build/ --target docfx/all \
&& rm -f $HOME/doc-pipeline/testdata/cpp/* \
&& env -C $HOME/doc-pipeline/testdata/cpp $PWD/.build/docfx/doxygen2docfx $PUBLISH/secretmanager/xml/secretmanager.doxygen.xml secretmanager 2.9.0
sed '1,2d' build-out/xrefmap.yml >>$HOME/doc-pipeline/testdata/cpp/toc.yml
sed -i '6d' $HOME/doc-pipeline/testdata/cpp/docs.metadata.json
env -C $HOME/doc-pipeline \
INPUT=testdata/cpp \
TRAMPOLINE_BUILD_FILE=./generate.sh \
TRAMPOLINE_IMAGE=gcr.io/cloud-devrel-kokoro-resources/docfx \
TRAMPOLINE_DOCKERFILE=docfx/Dockerfile ci/trampoline_v2.sh
From time to time we update Doxygen and that may result in schema changes.
Detecting these changes may be useful to design the corresponding changes to the
doxygen2docfx tool.
The schema definition can be found in the Doxygen GitHub Repository. Look for xml/compound.xsd