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