diff --git a/cmake-modules/AzureDoxygen.cmake b/cmake-modules/AzureDoxygen.cmake index 7a3469571..362e0cf05 100644 --- a/cmake-modules/AzureDoxygen.cmake +++ b/cmake-modules/AzureDoxygen.cmake @@ -9,7 +9,7 @@ function(generate_documentation PROJECT_NAME PROJECT_VERSION) if(BUILD_DOCUMENTATION) - find_package(Doxygen REQUIRED doxygen) + find_package(Doxygen 1.9.7 REQUIRED doxygen) set(DOXYGEN_PROJECT_NAME ${PROJECT_NAME}) set(DOXYGEN_PROJECT_NUMBER ${PROJECT_VERSION}) @@ -33,6 +33,7 @@ function(generate_documentation PROJECT_NAME PROJECT_VERSION) set(DOXYGEN_HTML_HEADER ${CMAKE_SOURCE_DIR}/eng/docs/api/assets/header.html) set(DOXYGEN_HTML_FOOTER ${CMAKE_SOURCE_DIR}/eng/docs/api/assets/footer.html) set(DOXYGEN_HTML_STYLESHEET ${CMAKE_SOURCE_DIR}/eng/docs/api/assets/style.css) + set(DOXYGEN_PROJECT_LOGO ${CMAKE_SOURCE_DIR}/eng/common/docgeneration/assets/logo.svg) set(DOXYGEN_GENERATE_XML YES) set(DOXYGEN_GENERATE_LATEX NO) @@ -43,6 +44,6 @@ function(generate_documentation PROJECT_NAME PROJECT_VERSION) doxygen_add_docs(${PROJECT_NAME}-docs ALL - COMMENT "Generate documentation for ${PROJECT_NAME}") + COMMENT "Generate documentation for ${PROJECT_NAME} with Doxygen Version ${DOXYGEN_VERSION}") endif() endfunction() diff --git a/eng/docs/api/assets/DoxygenLayout.xml b/eng/docs/api/assets/DoxygenLayout.xml index e8756a5b9..50676f7f0 100644 --- a/eng/docs/api/assets/DoxygenLayout.xml +++ b/eng/docs/api/assets/DoxygenLayout.xml @@ -1,5 +1,5 @@ - + @@ -9,37 +9,39 @@ + + - + - + - + - + - + - + @@ -103,6 +105,7 @@ + @@ -126,6 +129,15 @@ + + + + + + + + + @@ -139,6 +151,7 @@ + @@ -172,6 +185,7 @@ + diff --git a/eng/docs/api/assets/README.md b/eng/docs/api/assets/README.md new file mode 100644 index 000000000..4fe38ca7c --- /dev/null +++ b/eng/docs/api/assets/README.md @@ -0,0 +1,250 @@ +# Doxygen Template for C++ API Documentation + +When upgrading Doxygen, the following customizations have been made. + +## Export Doxygen Templates + +Doxygen templates have several parts: + +1. Doxygen Layout file `DoxygenLayout.xml` +1. Template files: + 1. `header.html` + 1. `footer.html` + 1. `style.css` (renamed from `customdoxygen.css`) + +Further documentation on customizing Doxygen can be found here: https://www.doxygen.nl/manual/customize.html + +To export the layout file: + +```powershell +cd eng\docs\api\assets +doxygen -l +``` + +To export the HTML/CSS files: + +```powershell +cd eng\docs\api\assets +doxygen -w html header.html footer.html style.css +``` + +## Configure templates + +### DoxygenLayout.xml + +Around line 6, change: + +```xml + +``` + +To read: + +```xml + +``` + +### header.html + +In the `` of the page add the following snippets: + +Add Google analytics tag: + +```html + + + +``` + +Add logic that populates and handles interactions with the version dropdown: + +```html + + +``` + +For the following look for and replace the sections bounded by +`` and `` with the following: + +In the project name section add the version selection dropdown in the +PROJECT_NUMBER section: + +```html + + +
+
+ +
+ $projectname + + + + + + + + + + +
+
$projectbrief
+ + +``` + +### footer.html + +No changes + +### style.css + +Stylesheet changes may require more work to properly incoporate into the layout. +To be successful here when iterating through changes, make changes in the +browser's "inspect element" tools and then copy those changes to the stylesheet +file. Here are the most obvious changes: + +Add these variables: + +```css + --title-foreground-color: white; +``` + +Change the title background color: + +```css + --title-background-color: rgb(0, 113, 197); +``` + +Change `#projectlogo`: + +```css + #projectlogo + { + text-align: center; + vertical-align: bottom; + border-collapse: separate; + padding-left: 8px; + } +``` + +Change `#projectname`: + +```css + #projectname + { + font-size: 200%; + font-family: var(--font-family-title); + margin: 0px; + padding: 2px 0px; + color: var(--title-foreground-color); + + #versionSelector { + font-size: 24px; + } + } +``` + +## How it's wired up + +See `cmake-modules/AzureDoxygen.cmake` to see how the layout files and and +templates are incorporated into the doxygen build. The build uses `logo.svg` +from `eng/common/docgeneration` instead of the repo-specific folder in +`eng/docs/api/assets`. diff --git a/eng/docs/api/assets/footer.html b/eng/docs/api/assets/footer.html index ff8fbe6f9..c1ae83f0f 100644 --- a/eng/docs/api/assets/footer.html +++ b/eng/docs/api/assets/footer.html @@ -1,20 +1,16 @@ - +
-$generatedby   -doxygen - $doxygenversion +$generatedby doxygen $doxygenversion
diff --git a/eng/docs/api/assets/header.html b/eng/docs/api/assets/header.html index 0323d8b5c..b4483f3bd 100644 --- a/eng/docs/api/assets/header.html +++ b/eng/docs/api/assets/header.html @@ -1,14 +1,20 @@ - + - + - + $projectname: $title $title + + + + + +