You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@lucenenet.apache.org by ni...@apache.org on 2020/11/18 20:50:39 UTC
[lucenenet] 01/06: re-adds automation step to assign the title in
the docs based on environment variable,
updates docs script to ensure that the base url is correctly set for the
live site, updates the docs building docs to be a bit more clear
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 68de3383157d1c4b3d9f0a3dcc8363358086e810
Author: Shannon <sd...@gmail.com>
AuthorDate: Tue Sep 29 11:46:17 2020 +1000
re-adds automation step to assign the title in the docs based on environment variable, updates docs script to ensure that the base url is correctly set for the live site, updates the docs building docs to be a bit more clear
---
.../EnvironmentVariableInlineRule.cs | 74 +++++++++++-----------
.../LuceneDocsPlugins/LuceneDfmEngineCustomizer.cs | 4 +-
websites/apidocs/docs.ps1 | 14 ++--
websites/apidocs/index.md | 17 ++---
websites/site/contributing/documentation.md | 29 +++++++--
5 files changed, 81 insertions(+), 57 deletions(-)
diff --git a/src/docs/LuceneDocsPlugins/EnvironmentVariableInlineRule.cs b/src/docs/LuceneDocsPlugins/EnvironmentVariableInlineRule.cs
index 2c06356..7fc8b34 100644
--- a/src/docs/LuceneDocsPlugins/EnvironmentVariableInlineRule.cs
+++ b/src/docs/LuceneDocsPlugins/EnvironmentVariableInlineRule.cs
@@ -17,40 +17,40 @@
* under the License.
*/
-//using System;
-//using System.Collections.Immutable;
-//using System.Text.RegularExpressions;
-//using Microsoft.DocAsCode.MarkdownLite;
-
-//namespace LuceneDocsPlugins
-//{
-// public class EnvironmentVariableInlineRule : IMarkdownRule
-// {
-// // give it a name
-// public string Name => "EnvVarToken";
-
-// // define my regex to match
-// private static readonly Regex _envVarRegex = new Regex(@"^\[EnvVar:(\w+?)\]", RegexOptions.Compiled);
-
-// // process the match
-// public IMarkdownToken TryMatch(IMarkdownParser parser, IMarkdownParsingContext context)
-// {
-// // TODO: This does not process this token from within a code block like
-
-// // ```
-// // dotnet tool install lucene-cli -g --version [EnvVar: LuceneNetVersion]
-// // ```
-
-// var match = _envVarRegex.Match(context.CurrentMarkdown);
-// if (match.Length == 0) return null;
-
-// var envVar = match.Groups[1].Value;
-// var text = Environment.GetEnvironmentVariable(envVar);
-// if (text == null) return null;
-
-// // 'eat' the characters of the current markdown token so they anr
-// var sourceInfo = context.Consume(match.Length);
-// return new MarkdownTextToken(this, parser.Context, text, sourceInfo);
-// }
-// }
-//}
\ No newline at end of file
+using System;
+using System.Collections.Immutable;
+using System.Text.RegularExpressions;
+using Microsoft.DocAsCode.MarkdownLite;
+
+namespace LuceneDocsPlugins
+{
+ public class EnvironmentVariableInlineRule : IMarkdownRule
+ {
+ // give it a name
+ public string Name => "EnvVarToken";
+
+ // define my regex to match
+ private static readonly Regex _envVarRegex = new Regex(@"^\<EnvVar:(\w+?)\>", RegexOptions.Compiled);
+
+ // process the match
+ public IMarkdownToken TryMatch(IMarkdownParser parser, IMarkdownParsingContext context)
+ {
+ // TODO: This does not process this token from within a code block like
+
+ // ```
+ // dotnet tool install lucene-cli -g --version [EnvVar: LuceneNetVersion]
+ // ```
+
+ var match = _envVarRegex.Match(context.CurrentMarkdown);
+ if (match.Length == 0) return null;
+
+ var envVar = match.Groups[1].Value;
+ var text = Environment.GetEnvironmentVariable(envVar);
+ if (text == null) return null;
+
+ // 'eat' the characters of the current markdown token so they anr
+ var sourceInfo = context.Consume(match.Length);
+ return new MarkdownTextToken(this, parser.Context, text, sourceInfo);
+ }
+ }
+}
\ No newline at end of file
diff --git a/src/docs/LuceneDocsPlugins/LuceneDfmEngineCustomizer.cs b/src/docs/LuceneDocsPlugins/LuceneDfmEngineCustomizer.cs
index 135aab2..6bfd711 100644
--- a/src/docs/LuceneDocsPlugins/LuceneDfmEngineCustomizer.cs
+++ b/src/docs/LuceneDocsPlugins/LuceneDfmEngineCustomizer.cs
@@ -32,8 +32,8 @@ namespace LuceneDocsPlugins
{
public void Customize(DfmEngineBuilder builder, IReadOnlyDictionary<string, object> parameters)
{
- //// insert inline rule at the top
- //builder.InlineRules = builder.InlineRules.Insert(0, new EnvironmentVariableInlineRule());
+ // insert inline rule at the top
+ builder.InlineRules = builder.InlineRules.Insert(0, new EnvironmentVariableInlineRule());
// insert block rule above header rule. Why? I dunno, that's what the docs say:
// https://dotnet.github.io/docfx/tutorial/intro_markdown_lite.html#select-token-kind
diff --git a/websites/apidocs/docs.ps1 b/websites/apidocs/docs.ps1
index fd42cf0..f30cc70 100644
--- a/websites/apidocs/docs.ps1
+++ b/websites/apidocs/docs.ps1
@@ -29,11 +29,15 @@ param (
[Parameter(Mandatory = $false)]
[string] $LogLevel = 'Warning',
[Parameter(Mandatory = $false)]
- [string] $BaseUrl = 'http://localhost:8080',
- [Parameter(Mandatory = $false)]
- [int] $StagingPort = 8080
+ [string] $BaseUrl = 'https://lucenenet.apache.org/docs/'
)
+# if the base URL is the lucene live site default value we also need to include the version
+if ($BaseUrl -eq 'https://lucenenet.apache.org/docs/') {
+ $BaseUrl += $LuceneNetVersion + "/"
+}
+Write-Host "Base URL for xref map set to $BaseUrl"
+
[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12
$PSScriptFilePath = (Get-Item $MyInvocation.MyCommand.Path).FullName
@@ -56,7 +60,7 @@ $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.56/docfx.zip" -OutFile $DocFxZip -TimeoutSec 60
+ Invoke-WebRequest "https://github.com/dotnet/docfx/releases/download/v2.56.2/docfx.zip" -OutFile $DocFxZip -TimeoutSec 60
#unzip
Expand-Archive $DocFxZip -DestinationPath (Join-Path -Path $ToolsFolder -ChildPath "docfx")
@@ -177,7 +181,7 @@ if ($? -and $DisableBuild -eq $false) {
$DocFxLog = Join-Path -Path $ApiDocsFolder "obj\${proj}.build.log"
- # build the output
+ # build the output
Write-Host "Building site output for $projFile..."
# Before we build the site we have to clear the frickin docfx cache!
diff --git a/websites/apidocs/index.md b/websites/apidocs/index.md
index b4a9be9..3d19dc3 100644
--- a/websites/apidocs/index.md
+++ b/websites/apidocs/index.md
@@ -3,15 +3,16 @@ title: Lucene.Net Docs - The documentation website for Lucene.Net
description: The documentation website for Lucene.Net
---
-# Apache Lucene.Net 4.8.0-beta00009 Documentation
+Apache Lucene.Net <EnvVar:LuceneNetVersion> Documentation
+===============
----
+---------------
-Lucene is a _.NET full-text search engine_. Lucene.NET is not a complete application,
+Lucene is a _.NET full-text search engine_. Lucene.NET is not a complete application,
but rather a code library and API that can easily be used to add search capabilities
to applications.
-This is the official API documentation for **Apache Lucene.NET 4.8.0-beta00009**.
+This is the official API documentation for __Apache Lucene.NET <EnvVar:LuceneNetVersion>__.
## Getting Started
@@ -28,10 +29,10 @@ on some of the conceptual or inner details of Lucene:
## Reference Documents
-- [Changes](https://github.com/apache/lucenenet/releases/tag/Lucene.Net_4_8_0_beta00007): List of changes in this release.
-- System Requirements: Minimum and supported .NET versions. **TODO: Add link**
-- Migration Guide: What changed in Lucene 4; how to migrate code from Lucene 3.x. **TODO: Add link**
-- [File Formats](xref:Lucene.Net.Codecs.Lucene46) : Guide to the supported index format used by Lucene. This can be customized by using [an alternate codec](xref:Lucene.Net.Codecs).
+- [Changes](https://github.com/apache/lucenenet/releases/tag/<EnvVar:LuceneNetReleaseTag>): List of changes in this release.
+- System Requirements: Minimum and supported .NET versions. __TODO: Add link__
+- Migration Guide: What changed in Lucene 4; how to migrate code from Lucene 3.x. __TODO: Add link__
+- [File Formats](xref:Lucene.Net.Codecs.Lucene46) : Guide to the supported index format used by Lucene. This can be customized by using [an alternate codec](xref:Lucene.Net.Codecs).
- [Search and Scoring in Lucene](xref:Lucene.Net.Search): Introduction to how Lucene scores documents.
- [Classic Scoring Formula](xref:Lucene.Net.Search.Similarities.TFIDFSimilarity): Formula of Lucene's classic [Vector Space](http://en.wikipedia.org/wiki/Vector_Space_Model) implementation. (look [here](xref:Lucene.Net.Search.Similarities) for other models)
- [Classic QueryParser Syntax](xref:Lucene.Net.QueryParsers.Classic): Overview of the Classic QueryParser's syntax and features.
diff --git a/websites/site/contributing/documentation.md b/websites/site/contributing/documentation.md
index 032b71f..d66bc69 100644
--- a/websites/site/contributing/documentation.md
+++ b/websites/site/contributing/documentation.md
@@ -50,13 +50,32 @@ 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: `/websites/apidocs/docs.ps1`. You don't have to pass any parameters in and it will build the site and host it at [http://localhost:8080](http://localhost:8080).
+To build the api docs and run it on your machine, run the powershell script `docs.ps1`. For example:
-The script has 3 parameters:
+```
+/websites/apidocs/docs.ps1 -ServeDocs -LuceneNetVersion 4.8.0-beta00008 -BaseUrl http://localhost:8080
+```
-- `-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` _(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:8080](http://localhost:8080). _(Ensure to pass in the current version of Lucene.Net you are building.)_
+
+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.
+
+The script has several parameters:
+
+* `-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.
### File/folder structure