Skip to content

Commit f478fee

Browse files
smailletsmaillet
authored
Implements UbiquityDotNET#2 - Add build version to generated docs. (UbiquityDotNET#15)
Co-authored-by: smaillet <[email protected]>
1 parent f9157d8 commit f478fee

File tree

6 files changed

+216
-12
lines changed

6 files changed

+216
-12
lines changed

‎.gitignore‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -291,3 +291,4 @@ __pycache__/
291291
/tools
292292
*.binlog
293293
/GeneratedVersion.props
294+
/docfx/CurrentVersionInfo.json

‎Build-Docs.ps1‎

Lines changed: 9 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -70,18 +70,18 @@ try
7070
# Thus, for now, this uses the docfx build phase.]
7171
"$([DateTime]::UtcNow.ToString('o'))" | Out-File -Path (Join-Path $docsOutputPath '.nojekyll')
7272

73-
#TODO: Find a way to leverage the build version information programmatically
74-
# One option used in other repos, is to create a dummy project and use the generated
75-
# Properties to save to a JSON file... That's dodgy at best for something so common as this...
76-
# Perhaps this repo could build a .NET tool that used the versioning library itself and that
77-
# could produce the version numbering for use in docs builds. Such use would require tests to
78-
# validate that the behavior of the versioning library matches that of the build task, but it
79-
# should have such testing anyway.
80-
$fullBuildNumber = '<build version unavailable>'
81-
8273
push-location './docfx'
8374
try
8475
{
76+
Write-Information "Generating Version JSON"
77+
Invoke-External dotnet msbuild -restore '-target:GenerateVersionJson' documentation.msbuildproj
78+
if(!(Test-Path -PathType Leaf 'CurrentVersionInfo.json'))
79+
{
80+
throw "CurrentVersionInfo.json - missing/not created!"
81+
}
82+
83+
$versionInfo = Get-Content ./CurrentVersionInfo.json | ConvertFrom-Json -AsHashTable
84+
$fullBuildNumber = $versionInfo['FullBuildNumber']
8585
Write-Information "Building docs [FullBuildNumber=$fullBuildNumber]"
8686
Invoke-External docfx '-m' _buildVersion=$fullBuildNumber '-o' $docsOutputPath
8787
}

‎docfx/documentation.msbuildproj‎

Lines changed: 40 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,9 +6,12 @@
66
Bug is that anything cares or sets a default that the IDE can't set causing it to occur.
77
-->
88
<Platform Condition="'$(Platform)'=='x86'">AnyCPU</Platform>
9+
<ManagePackageVersionsCentrally>true</ManagePackageVersionsCentrally>
910
</PropertyGroup>
11+
1012
<PropertyGroup Condition="'$(Configuration)|$(Platform)'=='Debug|AnyCPU'" />
1113
<PropertyGroup Condition="'$(Configuration)|$(Platform)'=='Release|AnyCPU'" />
14+
1215
<!--
1316
This projects serves as a convenient placeholder to reference the doc files. It uses project relative include
1417
and exclude patterns to simplify referencing ALL files but skipping over the generated API files.
@@ -34,4 +37,40 @@
3437
<Target Name="AlwaysRun" BeforeTargets="AfterBuild">
3538
<Message Importance="High" Text="NOTE: Building $(MSBuildProjectFile) does NOTHING, docs are built using the docfx tool. This project is simply a convenient placeholder for organizing/editing files" />
3639
</Target>
37-
</Project>
40+
41+
<!--
42+
Target to generate the versioning JSON file for consumption by the docs scripts. This target is explicitly called out
43+
by the build scripts to generate the JSON file with all the version details from Ubiquity.NET.Versioning.Build.Tasks.
44+
The `PrepareVersioningForBuild` target comes from there.
45+
-->
46+
<Target Name="GenerateVersionJson" DependsOnTargets="PrepareVersioningForBuild">
47+
<Error Condition="'$(FullBuildNumber)'==''" Text="FullBuildNumber not available!"/>
48+
<Message Importance="normal" Text=" BuildTime: $(BuildTime)"/>
49+
<Message Importance="normal" Text=" FullBuildNumber: $(FullBuildNumber)"/>
50+
<Message Importance="normal" Text=" BuildMajor: $(BuildMajor)"/>
51+
<Message Importance="normal" Text=" BuildMinor: $(BuildMinor)"/>
52+
<Message Importance="normal" Text=" BuildPatch: $(BuildPatch)"/>
53+
<Message Importance="normal" Text=" PreReleaseName: $(PreReleaseName)"/>
54+
<Message Importance="normal" Text=" PreReleaseNumber: $(PreReleaseNumber)"/>
55+
<Message Importance="normal" Text=" PreReleaseFix: $(PreReleaseFix)"/>
56+
<Message Importance="normal" Text=" BuildMeta: $(BuildMeta)"/>
57+
<Message Importance="normal" Text=" CiBuildName: $(CiBuildName)"/>
58+
<Message Importance="normal" Text=" CiBuildIndex: $(CiBuildIndex)"/>
59+
<ItemGroup>
60+
<__Line Include="{"/>
61+
<__Line Include=" &quot;FullBuildNumber&quot; : &quot;$(FullBuildNumber)&quot;," />
62+
<__Line Include=" &quot;BuildMajor&quot; : $(BuildMajor)," />
63+
<__Line Include=" &quot;BuildMinor&quot; : $(BuildMinor)," />
64+
<__Line Include=" &quot;BuildPatch&quot; : $(BuildPatch)," />
65+
<__Line Include=" &quot;PreReleaseName&quot; : &quot;$(PreReleaseName)&quot;," />
66+
<__Line Include=" &quot;CiBuildName&quot; : &quot;$(CiBuildName)&quot;," />
67+
<__Line Include=" &quot;CiBuildIndex&quot; : $(CiBuildIndex)," />
68+
<__Line Condition="'$(PreReleaseNumber)'!=''" Include="&quot;PreReleaseNumber&quot; : $(PreReleaseNumber)," />
69+
<__Line Condition="'$(PreReleaseFix)'!=''" Include="&quot;PreReleaseFix&quot; : $(PreReleaseFix)," />
70+
<__Line Condition="'$(BuildMeta)'!=''" Include="&quot;BuildMeta&quot; : &quot;$(BuildMeta)&quot;," />
71+
<__Line Include="}"/>
72+
</ItemGroup>
73+
<WriteLinesToFile File="CurrentVersionInfo.json" Lines="@(__Line)" Overwrite="true"/>
74+
</Target>
75+
76+
</Project>

‎docfx/templates/Ubiquity/layout/_master.tmpl‎

Lines changed: 160 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,160 @@
1+
{{!Licensed to the .NET Foundation under one or more agreements. The .NET Foundation licenses this file to you under the MIT license.}}
2+
{{!include(/^public/.*/)}}
3+
{{!include(favicon.ico)}}
4+
{{!include(logo.svg)}}
5+
<!DOCTYPE html>
6+
<html {{#_lang}}lang="{{_lang}}"{{/_lang}}>
7+
<head>
8+
<meta charset="utf-8">
9+
{{#redirect_url}}
10+
<meta http-equiv="refresh" content="0;URL='{{redirect_url}}'">
11+
{{/redirect_url}}
12+
{{^redirect_url}}
13+
<title>{{#title}}{{title}}{{/title}}{{^title}}{{>partials/title}}{{/title}} {{#_appTitle}}| {{_appTitle}} {{/_appTitle}}</title>
14+
<meta name="viewport" content="width=device-width, initial-scale=1.0">
15+
<meta name="title" content="{{#title}}{{title}}{{/title}}{{^title}}{{>partials/title}}{{/title}} {{#_appTitle}}| {{_appTitle}} {{/_appTitle}}">
16+
{{#_description}}<meta name="description" content="{{_description}}">{{/_description}}
17+
{{#description}}<meta name="description" content="{{description}}">{{/description}}
18+
<link rel="icon" href="{{_rel}}{{{_appFaviconPath}}}{{^_appFaviconPath}}favicon.ico{{/_appFaviconPath}}">
19+
<link rel="stylesheet" href="{{_rel}}public/docfx.min.css">
20+
<link rel="stylesheet" href="{{_rel}}public/main.css">
21+
<meta name="docfx:navrel" content="{{_navRel}}">
22+
<meta name="docfx:tocrel" content="{{_tocRel}}">
23+
{{#_noindex}}<meta name="searchOption" content="noindex">{{/_noindex}}
24+
{{#_enableSearch}}<meta name="docfx:rel" content="{{_rel}}">{{/_enableSearch}}
25+
{{#_disableNewTab}}<meta name="docfx:disablenewtab" content="true">{{/_disableNewTab}}
26+
{{#_disableTocFilter}}<meta name="docfx:disabletocfilter" content="true">{{/_disableTocFilter}}
27+
{{#docurl}}<meta name="docfx:docurl" content="{{docurl}}">{{/docurl}}
28+
<meta name="loc:inThisArticle" content="{{__global.inThisArticle}}">
29+
<meta name="loc:searchResultsCount" content="{{__global.searchResultsCount}}">
30+
<meta name="loc:searchNoResults" content="{{__global.searchNoResults}}">
31+
<meta name="loc:tocFilter" content="{{__global.tocFilter}}">
32+
<meta name="loc:nextArticle" content="{{__global.nextArticle}}">
33+
<meta name="loc:prevArticle" content="{{__global.prevArticle}}">
34+
<meta name="loc:themeLight" content="{{__global.themeLight}}">
35+
<meta name="loc:themeDark" content="{{__global.themeDark}}">
36+
<meta name="loc:themeAuto" content="{{__global.themeAuto}}">
37+
<meta name="loc:changeTheme" content="{{__global.changeTheme}}">
38+
<meta name="loc:copy" content="{{__global.copy}}">
39+
<meta name="loc:downloadPdf" content="{{__global.downloadPdf}}">
40+
41+
<script type="module" src="./{{_rel}}public/docfx.min.js"></script>
42+
43+
<script>
44+
const theme = localStorage.getItem('theme') || 'auto'
45+
document.documentElement.setAttribute('data-bs-theme', theme === 'auto' ? (window.matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light') : theme)
46+
</script>
47+
48+
{{#_googleAnalyticsTagId}}
49+
<script async src="https://www.googletagmanager.com/gtag/js?id={{_googleAnalyticsTagId}}"></script>
50+
<script>
51+
window.dataLayer = window.dataLayer || [];
52+
function gtag() { dataLayer.push(arguments); }
53+
gtag('js', new Date());
54+
gtag('config', '{{_googleAnalyticsTagId}}');
55+
</script>
56+
{{/_googleAnalyticsTagId}}
57+
{{/redirect_url}}
58+
</head>
59+
60+
{{^redirect_url}}
61+
<body class="tex2jax_ignore" data-layout="{{_layout}}{{layout}}" data-yaml-mime="{{yamlmime}}">
62+
<header class="bg-body border-bottom">
63+
{{^_disableNavbar}}
64+
<nav id="autocollapse" class="navbar navbar-expand-md" role="navigation">
65+
<div class="container-xxl flex-nowrap">
66+
<a class="navbar-brand" href="{{_appLogoUrl}}{{^_appLogoUrl}}{{_rel}}index.html{{/_appLogoUrl}}">
67+
<img id="logo" class="svg" src="{{_rel}}{{{_appLogoPath}}}{{^_appLogoPath}}logo.svg{{/_appLogoPath}}" alt="{{_appName}}" >
68+
{{_appName}}
69+
</a>
70+
<button class="btn btn-lg d-md-none border-0" type="button" data-bs-toggle="collapse" data-bs-target="#navpanel" aria-controls="navpanel" aria-expanded="false" aria-label="Toggle navigation">
71+
<i class="bi bi-three-dots"></i>
72+
</button>
73+
<div class="collapse navbar-collapse" id="navpanel">
74+
<div id="navbar">
75+
{{#_enableSearch}}
76+
<form class="search" role="search" id="search">
77+
<i class="bi bi-search"></i>
78+
<input class="form-control" id="search-query" type="search" disabled placeholder="{{__global.search}}" autocomplete="off" aria-label="Search">
79+
</form>
80+
{{/_enableSearch}}
81+
</div>
82+
</div>
83+
</div>
84+
</nav>
85+
{{/_disableNavbar}}
86+
</header>
87+
88+
<main class="container-xxl">
89+
{{^_disableToc}}
90+
<div class="toc-offcanvas">
91+
<div class="offcanvas-md offcanvas-start" tabindex="-1" id="tocOffcanvas" aria-labelledby="tocOffcanvasLabel">
92+
<div class="offcanvas-header">
93+
<h5 class="offcanvas-title" id="tocOffcanvasLabel">Table of Contents</h5>
94+
<button type="button" class="btn-close" data-bs-dismiss="offcanvas" data-bs-target="#tocOffcanvas" aria-label="Close"></button>
95+
</div>
96+
<div class="offcanvas-body">
97+
<nav class="toc" id="toc"></nav>
98+
</div>
99+
</div>
100+
</div>
101+
{{/_disableToc}}
102+
103+
<div class="content">
104+
<div class="actionbar">
105+
{{^_disableToc}}
106+
<button class="btn btn-lg border-0 d-md-none"
107+
type="button" data-bs-toggle="offcanvas" data-bs-target="#tocOffcanvas"
108+
aria-controls="tocOffcanvas" aria-expanded="false" aria-label="Show table of contents">
109+
<i class="bi bi-list"></i>
110+
</button>
111+
{{/_disableToc}}
112+
113+
{{^_disableBreadcrumb}}
114+
<nav id="breadcrumb"></nav>
115+
{{/_disableBreadcrumb}}
116+
</div>
117+
118+
<article data-uid="{{uid}}">
119+
{{!body}}
120+
</article>
121+
122+
{{^_disableContribution}}
123+
<div class="contribution d-print-none">
124+
{{#sourceurl}}
125+
<a href="{{sourceurl}}" class="edit-link">{{__global.improveThisDoc}}</a>
126+
{{/sourceurl}}
127+
{{^sourceurl}}{{#docurl}}
128+
<a href="{{docurl}}" class="edit-link">{{__global.improveThisDoc}}</a>
129+
{{/docurl}}{{/sourceurl}}
130+
</div>
131+
{{/_disableContribution}}
132+
133+
{{^_disableNextArticle}}
134+
<div class="next-article d-print-none border-top" id="nextArticle"></div>
135+
{{/_disableNextArticle}}
136+
137+
</div>
138+
139+
{{^_disableAffix}}
140+
<div class="affix">
141+
<nav id="affix"></nav>
142+
</div>
143+
{{/_disableAffix}}
144+
</main>
145+
146+
{{#_enableSearch}}
147+
<div class="container-xxl search-results" id="search-results"></div>
148+
{{/_enableSearch}}
149+
150+
<footer class="border-top text-secondary">
151+
<div class="container-xxl">
152+
<div class="flex-fill">
153+
{{{_appFooter}}}{{^_appFooter}}<span>Made with <a href="https://dotnet.github.io/docfx">docfx</a></span>{{/_appFooter}}
154+
{{#_buildVersion}}- Build: {{_buildVersion}}{{/_buildVersion}}
155+
</div>
156+
</div>
157+
</footer>
158+
</body>
159+
{{/redirect_url}}
160+
</html>

‎docfx/templates/Ubiquity/readme.md‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,3 +7,9 @@ This template adds support to the modern template to disable some features like
77
members. It would be nice if docfx didn't even generate such things, but it has no knobs to
88
control that so it can only be disabled by a custom CSS to hide the content at page render
99
time on the client after it is generated and downloaded. :unamused:
10+
11+
## layout/_master.tmpl
12+
This is mostly borrowed from the official DocFX `modern` template. However, the build
13+
version number was added to the footer. Unfortunately no simpler means was found to do
14+
that.
15+

‎docfx/toc.yml‎

Lines changed: 0 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -11,5 +11,3 @@
1111
items:
1212
- name: Ubiquity.NET.Versioning
1313
href: versioning-lib/index.md
14-
- name: Ubiquity.NET.Versioning.Build.Tasks
15-
href: build-tasks/index.md

0 commit comments

Comments
 (0)