You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@lucenenet.apache.org by pa...@apache.org on 2024/09/15 22:02:41 UTC
(lucenenet) 01/09: WIP on updating docfx
This is an automated email from the ASF dual-hosted git repository.
paulirwin pushed a commit to branch issue/911
in repository https://gitbox.apache.org/repos/asf/lucenenet.git
commit 39366fcb98d93eb5b66e102e9aeb14bdcaacb25a
Author: Paul Irwin <pa...@gmail.com>
AuthorDate: Thu Jun 20 21:33:15 2024 -0600
WIP on updating docfx
---
websites/apidocs/docfx.global.json | 26 ++++++------
websites/apidocs/docfx.global.subsite.json | 8 +++-
websites/apidocs/docs.ps1 | 66 +++++-------------------------
websites/apidocs/toc.yml | 8 +++-
websites/apidocs/toc/toc.yml | 8 +++-
5 files changed, 45 insertions(+), 71 deletions(-)
diff --git a/websites/apidocs/docfx.global.json b/websites/apidocs/docfx.global.json
index b46149ea1..b6891a991 100644
--- a/websites/apidocs/docfx.global.json
+++ b/websites/apidocs/docfx.global.json
@@ -1,15 +1,15 @@
{
- "_appTitle": "Apache Lucene.NET 4.8.0-beta00016 Documentation",
- "_disableContribution": false,
- "_appFaviconPath": "logo/favicon.ico",
- "_enableSearch": true,
- "_appLogoPath": "logo/lucene-net-color.png",
- "_appFooter": "Copyright \u0026copy; 2022 The Apache Software Foundation, Licensed under the \u003ca href=\u0027http://www.apache.org/licenses/LICENSE-2.0\u0027 target=\u0027_blank\u0027\u003eApache License, Version 2.0\u003c/a\u003e\u003cbr/\u003e \u003csmall\u003eApache Lucene.Net, Lucene.Net, Apache, the Apache feather logo, and the Apache Lucene.Net project logo are trademarks of The Apache Software Foundation. \u003cbr/\u003eAll other marks mentioned may be trademarks or regist [...]
- "_gitContribute": {
- "repo": "https://github.com/apache/lucenenet",
- "branch": "docs/4.8.0-beta00016",
- "apiSpecFolder": "websites/apidocs/apiSpec",
- "tag": "Lucene.Net_4_8_0_beta00016"
- },
- "_gitSource": "https://github.com/apache/lucenenet.git"
+ "_appTitle": "Apache Lucene.NET 4.8.0-beta00016 Documentation",
+ "_disableContribution": false,
+ "_appFaviconPath": "logo/favicon.ico",
+ "_enableSearch": true,
+ "_appLogoPath": "logo/lucene-net-color.png",
+ "_appFooter": "Copyright © 2024 The Apache Software Foundation, Licensed under the <a href='http://www.apache.org/licenses/LICENSE-2.0' target='_blank'>Apache License, Version 2.0</a><br/> <small>Apache Lucene.Net, Lucene.Net, Apache, the Apache feather logo, and the Apache Lucene.Net project logo are trademarks of The Apache Software Foundation. <br/>All other marks mentioned may be trademarks or registered trademarks of their respective owners.</small>",
+ "_gitContribute": {
+ "repo": "https://github.com/apache/lucenenet",
+ "branch": "docs/4.8.0-beta00016",
+ "apiSpecFolder": "websites/apidocs/apiSpec",
+ "tag": "Lucene.Net_4_8_0_beta00016"
+ },
+ "_gitSource": "https://github.com/apache/lucenenet.git"
}
diff --git a/websites/apidocs/docfx.global.subsite.json b/websites/apidocs/docfx.global.subsite.json
index 6cf6b985f..565723383 100644
--- a/websites/apidocs/docfx.global.subsite.json
+++ b/websites/apidocs/docfx.global.subsite.json
@@ -1,4 +1,10 @@
-{
+{
"_rel": "https://lucenenet.apache.org/docs/4.8.0-beta00009/",
"_api": "https://lucenenet.apache.org/docs/4.8.0-beta00016/"
}
+
+
+
+
+
+
diff --git a/websites/apidocs/docs.ps1 b/websites/apidocs/docs.ps1
index 38728b50a..fc454689b 100644
--- a/websites/apidocs/docs.ps1
+++ b/websites/apidocs/docs.ps1
@@ -23,6 +23,7 @@ param (
[string] $LuceneNetVersion,
[switch] $ServeDocs = $false,
[switch] $Clean = $false,
+ [switch] $SkipToolInstall = $false, # to speed up iteration if you already have the tool installed
[switch] $DisableMetaData = $false,
[switch] $DisableBuild = $false,
[switch] $DisablePlugins = $false,
@@ -34,7 +35,7 @@ param (
[Parameter(Mandatory = $false)]
[int] $StagingPort = 8080
)
-$MinimumSdkVersion = "3.1.100" # Minimum Required .NET SDK (must not be a pre-release)
+$MinimumSdkVersion = "8.0.204" # Minimum Required .NET SDK (must not be a pre-release)
$ErrorActionPreference = "Stop"
@@ -57,36 +58,17 @@ $env:LuceneNetReleaseTag = $VCSLabel
$PSScriptFilePath = (Get-Item $MyInvocation.MyCommand.Path).FullName
$RepoRoot = (get-item $PSScriptFilePath).Directory.Parent.Parent.FullName;
$ApiDocsFolder = Join-Path -Path $RepoRoot -ChildPath "websites\apidocs";
-$ToolsFolder = Join-Path -Path $ApiDocsFolder -ChildPath "tools";
$CliIndexPath = Join-Path -Path $RepoRoot -ChildPath "src\dotnet\tools\lucene-cli\docs\index.md";
$TocPath1 = Join-Path -Path $ApiDocsFolder -ChildPath "toc.yml"
$TocPath2 = Join-Path -Path $ApiDocsFolder -ChildPath "toc\toc.yml"
$BreadcrumbPath = Join-Path -Path $ApiDocsFolder -ChildPath "docfx.global.subsite.json"
-#ensure the /build/tools folder
-New-Item $ToolsFolder -type directory -force
-
-if ($Clean) {
- Write-Host "Cleaning tools..."
- Remove-Item (Join-Path -Path $ToolsFolder "\*") -recurse -force -ErrorAction SilentlyContinue
-}
-
-New-Item "$ToolsFolder\tmp" -type directory -force
-
-# Go get docfx.exe if we don't have it
-New-Item "$ToolsFolder\docfx" -type directory -force
-$DocFxExe = "$ToolsFolder\docfx\docfx.exe"
-if (-not (test-path $DocFxExe)) {
- Write-Host "Retrieving docfx..."
- $DocFxZip = "$ToolsFolder\tmp\docfx.zip"
- Invoke-WebRequest "https://github.com/dotnet/docfx/releases/download/v2.58/docfx.zip" -OutFile $DocFxZip -TimeoutSec 60
-
- #unzip
- Expand-Archive $DocFxZip -DestinationPath (Join-Path -Path $ToolsFolder -ChildPath "docfx")
+# install docfx tool
+if ($SkipToolInstall -eq $false) {
+ Write-Host "Installing docfx global tool..."
+ dotnet tool install -g docfx --version 2.76.0
}
-Remove-Item -Recurse -Force "$ToolsFolder\tmp"
-
# delete anything that already exists
if ($Clean) {
Write-Host "Cleaning..."
@@ -168,13 +150,7 @@ if ($? -and $DisableMetaData -eq $false) {
# build the output
Write-Host "Building api metadata for $projFile..."
-
- if ($Clean) {
- & $DocFxExe metadata $projFile --log "$DocFxLog" --loglevel $LogLevel --force
- }
- else {
- & $DocFxExe metadata $projFile --log "$DocFxLog" --loglevel $LogLevel
- }
+ & docfx metadata $projFile --log "$DocFxLog" --logLevel $LogLevel
}
}
@@ -198,21 +174,7 @@ if ($? -and $DisableBuild -eq $false) {
# build the output
Write-Host "Building site output for $projFile..."
-
- # Specifying --force, --forcePostProcess and --cleanupCacheHistory
- # seems to be required in order for all xref links to resolve consistently across
- # all of the docfx builds (see https://dotnet.github.io/docfx/RELEASENOTE.html?tabs=csharp).
- # Previously we used to do this:
- # Remove-Item (Join-Path -Path $ApiDocsFolder "obj\.cache") -recurse -force -ErrorAction SilentlyContinue
- # to force remove the cache else the xref's wouldn't work correctly. So far with these new parameters
- # it seems much happier.
-
- if ($Clean) {
- & $DocFxExe build $projFile --log "$DocFxLog" --loglevel $LogLevel --force --debug --cleanupCacheHistory --force --forcePostProcess
- }
- else {
- & $DocFxExe build $projFile --log "$DocFxLog" --loglevel $LogLevel --debug --cleanupCacheHistory --force --forcePostProcess
- }
+ & docfx build $projFile --log "$DocFxLog" --logLevel $LogLevel --debug
# Add the baseUrl to the output xrefmap, see https://github.com/dotnet/docfx/issues/2346#issuecomment-356054027
$projFileJson = Get-Content $projFile | ConvertFrom-Json
@@ -239,18 +201,12 @@ if ($?) {
# build the output
Write-Host "Building docs..."
-
- if ($Clean) {
- & $DocFxExe $DocFxJsonSite --log "$DocFxLog" --loglevel $LogLevel --force --debug
- }
- else {
- & $DocFxExe $DocFxJsonSite --log "$DocFxLog" --loglevel $LogLevel --debug
- }
+ & docfx $DocFxJsonSite --log "$DocFxLog" --logLevel $LogLevel --debug
}
else {
# build + serve (for testing)
Write-Host "starting website..."
- & $DocFxExe $DocFxJsonSite --log "$DocFxLog" --loglevel $LogLevel --serve --port $StagingPort --debug
+ & docfx $DocFxJsonSite --log "$DocFxLog" --logLevel $LogLevel --serve --port $StagingPort --debug
}
}
@@ -258,4 +214,4 @@ if ($?) {
# and then many of these params can be excluded from the json file
# .\docfx.exe ..\..\docfx.core.json --globalMetadataFiles docfx.global.json --output _TEST --serve --force --loglevel Warning
-# docfx.exe --output TARGET --globalMetadataFiles docfx.global.json Warning
\ No newline at end of file
+# docfx.exe --output TARGET --globalMetadataFiles docfx.global.json Warning
diff --git a/websites/apidocs/toc.yml b/websites/apidocs/toc.yml
index 446bef5a3..1b9b2b681 100644
--- a/websites/apidocs/toc.yml
+++ b/websites/apidocs/toc.yml
@@ -1,7 +1,13 @@
-- name: Lucene.Net API
+- name: Lucene.Net API
topicHref: https://lucenenet.apache.org/docs/4.8.0-beta00016/
- name: Lucene.Net CLI
href: ../../src/dotnet/tools/lucene-cli/docs/
topicHref: ../../src/dotnet/tools/lucene-cli/docs/index.md
- name: Lucene.Net Website
href: https://lucenenet.apache.org/
+
+
+
+
+
+
diff --git a/websites/apidocs/toc/toc.yml b/websites/apidocs/toc/toc.yml
index f4c7b8d96..fd3ea32b8 100644
--- a/websites/apidocs/toc/toc.yml
+++ b/websites/apidocs/toc/toc.yml
@@ -1,6 +1,12 @@
-- name: Lucene.Net API
+- name: Lucene.Net API
topicHref: https://lucenenet.apache.org/docs/4.8.0-beta00016
- name: Lucene.Net CLI
topicHref: https://lucenenet.apache.org/docs/4.8.0-beta00016/cli/index.html
- name: Lucene.Net Website
topicHref: https://lucenenet.apache.org/
+
+
+
+
+
+