This is an automated email from the ASF dual-hosted git repository. nightowl888 pushed a commit to branch master in repository https://gitbox.apache.org/repos/asf/lucenenet.git
commit 7d555cb4c26859192c9e8ec5066543f29df8408f Author: Shannon <[email protected]> AuthorDate: Wed Nov 18 15:21:47 2020 +1100 streamlines the site build script to be inline with the docs and updates the docs accordingly --- websites/site/contributing/documentation.md | 44 +++++++++++++++++++---------- websites/site/site.ps1 | 18 +++++------- 2 files changed, 36 insertions(+), 26 deletions(-) diff --git a/websites/site/contributing/documentation.md b/websites/site/contributing/documentation.md index d66bc69..8728d64 100644 --- a/websites/site/contributing/documentation.md +++ b/websites/site/contributing/documentation.md @@ -18,12 +18,26 @@ To submit changes for the website, create a Pull Request to the [Lucene Git repo ### Build script -To build the website and run it on your machine, run the Powershell script: `/websites/site/site.ps1`. You don't have to pass any parameters in and it will build the site and host it at [http://localhost:8081](http://localhost:8081). +To build the website and run it on your machine, run the Powershell script: `/websites/site/site.ps1` with the `-ServeDocs` flag. For example: -The script has 2 optional parameters: +``` +/websites/site/site.ps1 -ServeDocs +``` + +When executed this will build the site and host it at [http://localhost:8081](http://localhost:8081). + +To build the website for release, run the script: + +``` +/websites/site/site.ps1 +``` + +This will build the site with all live parameters configured correctly and output the built static site into the `_site` folder. + +The script parameters are: -- `-ServeDocs` _(default is 1)_ The value of `1` means it will build the docs and host the site, if `0` is specified, it will build the static site to be hosted elsewhere. -- `-Clean` _(default is 0)_ The value of `1` means that it will clear all caches and tool files before it builds again. This is handy if a new version of docfx is available or if there's odd things occurring with the incremental build. +- `-ServeDocs` _(optional)_ A boolean switch. If present, it will build the docs and host the site. If not present it will build the static site to be hosted elsewhere. +- `-Clean` _(optional)_ A boolean switch. If present, it will clear all caches and tool files before it builds again. This is handy if a new version of docfx is available or if there's odd things occurring with the incremental build. ### File/folder structure @@ -50,7 +64,7 @@ The file/folder structure is within `/websites/site`: ### Build script -To build the api docs and run it on your machine, run the powershell script `docs.ps1`. For example: +To build the api docs and run it on your machine, run the Powershell script: `/websites/apidocs/docs.ps1`. For example: ``` /websites/apidocs/docs.ps1 -ServeDocs -LuceneNetVersion 4.8.0-beta00008 -BaseUrl http://localhost:8080 @@ -64,18 +78,18 @@ To build the api docs for release, run the script: /websites/apidocs/docs.ps1 -LuceneNetVersion 4.8.0-beta00008 ``` -This will build the site with all live parameters configured correctly and output the built static site into the `_site` folder. +This will build the site with all live parameters configured correctly and output the built static site into the `_site` folder. -The script has several parameters: +The script parameters are: -* `-LuceneNetVersion` _(mandatory)_ This is the Lucene.Net version including pre-release information that is being built. For example: `4.8.0-beta00008`. _(This value will correspond to the folder and branch name where the docs get hosted, see below)_ -* `-ServeDocs` _(optinonal)_ A boolean switch. If present, it will build the docs and host the site. If not present it will build the static site to be hosted elsewhere. -* `-Clean` _(optinonal)_ A boolean switch. If present, it will clear all caches and tool files before it builds again. This is handy if a new version of docfx is available or if there's odd things occuring with the incremental build. -* `-DisableMetaData` _(optinonal)_ A boolean switch. If present it will disable the docfx metadata build operation of the docs build. Can be handy when debugging the docs build. -* `-DisableBuild` _(optinonal)_ A boolean switch. If present it will disable the site building operation of the docs build. Can be handy when debugging the docs build. -* `-DisablePlugins` _(optinonal)_ A boolean switch. If present it will not build the custom Lucene.Net `DocumentationTools.sln` docsfx plugins and exclude them from the build. -* `-LogLevel` _(optinonal)_ Default is Warning. Options are: Diagnostic, Verbose, Info, Warning, Error. -* `-BaseUrl` _(optinonal)_ Default is https://lucenenet.apache.org/docs/. Used to set the base URL of the docfx xref map files for cross linking between project builds. +- `-LuceneNetVersion` _(mandatory)_ This is the Lucene.Net version including pre-release information that is being built. For example: `4.8.0-beta00008`. _(This value will correspond to the folder and branch name where the docs get hosted, see below)_ +* `-ServeDocs` _(optional)_ A boolean switch. If present, it will build the docs and host the site. If not present it will build the static site to be hosted elsewhere. +* `-Clean` _(optional)_ A boolean switch. If present, it will clear all caches and tool files before it builds again. This is handy if a new version of docfx is available or if there's odd things occurring with the incremental build. +* `-DisableMetaData` _(optional)_ A boolean switch. If present it will disable the docfx metadata build operation of the docs build. Can be handy when debugging the docs build. +* `-DisableBuild` _(optional)_ A boolean switch. If present it will disable the site building operation of the docs build. Can be handy when debugging the docs build. +* `-DisablePlugins` _(optional)_ A boolean switch. If present it will not build the custom Lucene.Net `DocumentationTools.sln` docsfx plugins and exclude them from the build. +* `-LogLevel` _(optional)_ Default is Warning. Options are: Diagnostic, Verbose, Info, Warning, Error. +* `-BaseUrl` _(optional)_ Default is https://lucenenet.apache.org/docs/. Used to set the base URL of the docfx xref map files for cross linking between project builds. ### File/folder structure diff --git a/websites/site/site.ps1 b/websites/site/site.ps1 index 0bac019..4b1d465 100644 --- a/websites/site/site.ps1 +++ b/websites/site/site.ps1 @@ -6,9 +6,9 @@ # The ASF licenses this file to You under the Apache License, Version 2.0 # (the ""License""); you may not use this file except in compliance with # the License. You may obtain a copy of the License at -# +# # http://www.apache.org/licenses/LICENSE-2.0 -# +# # Unless required by applicable law or agreed to in writing, software # distributed under the License is distributed on an ""AS IS"" BASIS, # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. @@ -18,12 +18,8 @@ # ----------------------------------------------------------------------------------- param ( - [Parameter(Mandatory=$false)] - [int] - $ServeDocs = 1, - [Parameter(Mandatory=$false)] - [int] - $Clean = 0, + [switch] $ServeDocs = $false, + [switch] $Clean = $false, # LogLevel can be: Diagnostic, Verbose, Info, Warning, Error [Parameter(Mandatory=$false)] [string] @@ -56,7 +52,7 @@ if (-not (test-path $DocFxExe)) { Write-Host "Retrieving docfx..." $DocFxZip = "$ToolsFolder\tmp\docfx.zip" - Invoke-WebRequest "https://github.com/dotnet/docfx/releases/download/v2.50/docfx.zip"; -OutFile $DocFxZip -TimeoutSec 60 + Invoke-WebRequest "https://github.com/dotnet/docfx/releases/download/v2.50/docfx.zip"; -OutFile $DocFxZip -TimeoutSec 60 #unzip Expand-Archive $DocFxZip -DestinationPath (Join-Path -Path $ToolsFolder -ChildPath "docfx") } @@ -75,9 +71,9 @@ if ($Clean -eq 1) { $DocFxJson = Join-Path -Path $SiteFolder "docfx.json" $DocFxLog = Join-Path -Path $SiteFolder "obj\docfx.log" -if($?) { +if($?) { if ($ServeDocs -eq 0){ - # build the output + # build the output Write-Host "Building docs..." & $DocFxExe build $DocFxJson -l "$DocFxLog" --loglevel $LogLevel }
