streamlines the site build script to be inline with the docs and updates the docs accordingly
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 @@
### 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
+```
-- `-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.
+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` _(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 @@
### 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 @@
/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 @@
{
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 @@
$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
}
