This is an automated email from the ASF dual-hosted git repository.
shazwazza pushed a commit to branch docs-may
in repository https://gitbox.apache.org/repos/asf/lucenenet.git
The following commit(s) were added to refs/heads/docs-may by this push:
new bd530cd Updates script to update docfx json prior to building adds
more docs
bd530cd is described below
commit bd530cd71927e8b919ffb0c621e2b9265c95b49f
Author: Shannon <[email protected]>
AuthorDate: Fri May 15 13:50:57 2020 +1000
Updates script to update docfx json prior to building adds more docs
---
src/docs/readme.md | 2 +
websites/apidocs/docfx.json | 265 ++++++++++++++++++++--------
websites/apidocs/docs.ps1 | 11 ++
websites/site/contributing/documentation.md | 51 +++++-
4 files changed, 256 insertions(+), 73 deletions(-)
diff --git a/src/docs/readme.md b/src/docs/readme.md
index 3476d01..eed80b5 100644
--- a/src/docs/readme.md
+++ b/src/docs/readme.md
@@ -9,6 +9,8 @@ This utility does a lot of edge case work to try to
automatically convert as muc
The source that this is executed against is this tag:
https://github.com/apache/lucene-solr/releases/tag/releases%2Flucene-solr%2F4.8.1
+See docs: https://lucenenet.apache.org/contributing/documentation.html#api-docs
+
## LuceneDocsPlugins
This is a DocFx custom extension. It is built and executed as part of the docs
build process to customize/extend some of the features in DocFx.
\ No newline at end of file
diff --git a/websites/apidocs/docfx.json b/websites/apidocs/docfx.json
index c65359a..5c110b4 100644
--- a/websites/apidocs/docfx.json
+++ b/websites/apidocs/docfx.json
@@ -6,13 +6,17 @@
"files": [
"Lucene.Net/Lucene.Net.csproj"
],
- "exclude": ["**/obj/**", "**/bin/**", "**/Lucene.Net.Test*/**"],
+ "exclude": [
+ "**/obj/**",
+ "**/bin/**",
+ "**/Lucene.Net.Test*/**"
+ ],
"src": "../../src"
}
],
"dest": "obj/docfx/api/Lucene.Net",
"properties": {
- "TargetFramework": "netstandard2.0"
+ "TargetFramework": "netstandard2.0"
}
},
{
@@ -21,13 +25,17 @@
"files": [
"Lucene.Net.Analysis.Common/Lucene.Net.Analysis.Common.csproj"
],
- "exclude": ["**/obj/**", "**/bin/**", "**/Lucene.Net.Test*/**"],
+ "exclude": [
+ "**/obj/**",
+ "**/bin/**",
+ "**/Lucene.Net.Test*/**"
+ ],
"src": "../../src"
}
],
"dest": "obj/docfx/api/Lucene.Net.Analysis.Common",
"properties": {
- "TargetFramework": "netstandard2.0"
+ "TargetFramework": "netstandard2.0"
}
},
{
@@ -36,13 +44,17 @@
"files": [
"Lucene.Net.Analysis.Kuromoji/Lucene.Net.Analysis.Kuromoji.csproj"
],
- "exclude": ["**/obj/**", "**/bin/**", "**/Lucene.Net.Test*/**"],
+ "exclude": [
+ "**/obj/**",
+ "**/bin/**",
+ "**/Lucene.Net.Test*/**"
+ ],
"src": "../../src"
}
],
"dest": "obj/docfx/api/Lucene.Net.Analysis.Kuromoji",
"properties": {
- "TargetFramework": "netstandard2.0"
+ "TargetFramework": "netstandard2.0"
}
},
{
@@ -51,13 +63,17 @@
"files": [
"Lucene.Net.Analysis.Morfologik/Lucene.Net.Analysis.Morfologik.csproj"
],
- "exclude": ["**/obj/**", "**/bin/**", "**/Lucene.Net.Test*/**"],
+ "exclude": [
+ "**/obj/**",
+ "**/bin/**",
+ "**/Lucene.Net.Test*/**"
+ ],
"src": "../../src"
}
],
"dest": "obj/docfx/api/Lucene.Net.Analysis.Morfologik",
"properties": {
- "TargetFramework": "netstandard2.0"
+ "TargetFramework": "netstandard2.0"
}
},
{
@@ -66,13 +82,17 @@
"files": [
"Lucene.Net.Analysis.OpenNLP/Lucene.Net.Analysis.OpenNLP.csproj"
],
- "exclude": ["**/obj/**", "**/bin/**", "**/Lucene.Net.Test*/**"],
+ "exclude": [
+ "**/obj/**",
+ "**/bin/**",
+ "**/Lucene.Net.Test*/**"
+ ],
"src": "../../src"
}
],
"dest": "obj/docfx/api/Lucene.Net.Analysis.OpenNLP",
"properties": {
- "TargetFramework": "netstandard2.0"
+ "TargetFramework": "netstandard2.0"
}
},
{
@@ -81,13 +101,17 @@
"files": [
"Lucene.Net.Analysis.Phonetic/Lucene.Net.Analysis.Phonetic.csproj"
],
- "exclude": ["**/obj/**", "**/bin/**", "**/Lucene.Net.Test*/**"],
+ "exclude": [
+ "**/obj/**",
+ "**/bin/**",
+ "**/Lucene.Net.Test*/**"
+ ],
"src": "../../src"
}
],
"dest": "obj/docfx/api/Lucene.Net.Analysis.Phonetic",
"properties": {
- "TargetFramework": "netstandard2.0"
+ "TargetFramework": "netstandard2.0"
}
},
{
@@ -96,13 +120,17 @@
"files": [
"Lucene.Net.Analysis.SmartCn/Lucene.Net.Analysis.SmartCn.csproj"
],
- "exclude": ["**/obj/**", "**/bin/**", "**/Lucene.Net.Test*/**"],
+ "exclude": [
+ "**/obj/**",
+ "**/bin/**",
+ "**/Lucene.Net.Test*/**"
+ ],
"src": "../../src"
}
],
"dest": "obj/docfx/api/Lucene.Net.Analysis.SmartCn",
"properties": {
- "TargetFramework": "netstandard2.0"
+ "TargetFramework": "netstandard2.0"
}
},
{
@@ -111,13 +139,17 @@
"files": [
"Lucene.Net.Analysis.Stempel/Lucene.Net.Analysis.Stempel.csproj"
],
- "exclude": ["**/obj/**", "**/bin/**", "**/Lucene.Net.Test*/**"],
+ "exclude": [
+ "**/obj/**",
+ "**/bin/**",
+ "**/Lucene.Net.Test*/**"
+ ],
"src": "../../src"
}
],
"dest": "obj/docfx/api/Lucene.Net.Analysis.Stempel",
"properties": {
- "TargetFramework": "netstandard2.0"
+ "TargetFramework": "netstandard2.0"
}
},
{
@@ -126,28 +158,36 @@
"files": [
"Lucene.Net.Benchmark/Lucene.Net.Benchmark.csproj"
],
- "exclude": ["**/obj/**", "**/bin/**", "**/Lucene.Net.Test*/**"],
+ "exclude": [
+ "**/obj/**",
+ "**/bin/**",
+ "**/Lucene.Net.Test*/**"
+ ],
"src": "../../src"
}
],
"dest": "obj/docfx/api/Lucene.Net.Benchmarks",
"properties": {
- "TargetFramework": "netstandard2.0"
+ "TargetFramework": "netstandard2.0"
}
- },
+ },
{
"src": [
{
"files": [
"Lucene.Net.Classification/Lucene.Net.Classification.csproj"
],
- "exclude": ["**/obj/**", "**/bin/**", "**/Lucene.Net.Test*/**"],
+ "exclude": [
+ "**/obj/**",
+ "**/bin/**",
+ "**/Lucene.Net.Test*/**"
+ ],
"src": "../../src"
}
],
"dest": "obj/docfx/api/Lucene.Net.Classification",
"properties": {
- "TargetFramework": "netstandard2.0"
+ "TargetFramework": "netstandard2.0"
}
},
{
@@ -156,13 +196,17 @@
"files": [
"Lucene.Net.Codecs/Lucene.Net.Codecs.csproj"
],
- "exclude": ["**/obj/**", "**/bin/**", "**/Lucene.Net.Test*/**"],
+ "exclude": [
+ "**/obj/**",
+ "**/bin/**",
+ "**/Lucene.Net.Test*/**"
+ ],
"src": "../../src"
}
],
"dest": "obj/docfx/api/Lucene.Net.Codecs",
"properties": {
- "TargetFramework": "netstandard2.0"
+ "TargetFramework": "netstandard2.0"
}
},
{
@@ -171,13 +215,17 @@
"files": [
"Lucene.Net.Expressions/Lucene.Net.Expressions.csproj"
],
- "exclude": ["**/obj/**", "**/bin/**", "**/Lucene.Net.Test*/**"],
+ "exclude": [
+ "**/obj/**",
+ "**/bin/**",
+ "**/Lucene.Net.Test*/**"
+ ],
"src": "../../src"
}
],
"dest": "obj/docfx/api/Lucene.Net.Expressions",
"properties": {
- "TargetFramework": "netstandard2.0"
+ "TargetFramework": "netstandard2.0"
}
},
{
@@ -186,13 +234,17 @@
"files": [
"Lucene.Net.Facet/Lucene.Net.Facet.csproj"
],
- "exclude": ["**/obj/**", "**/bin/**", "**/Lucene.Net.Test*/**"],
+ "exclude": [
+ "**/obj/**",
+ "**/bin/**",
+ "**/Lucene.Net.Test*/**"
+ ],
"src": "../../src"
}
],
"dest": "obj/docfx/api/Lucene.Net.Facet",
"properties": {
- "TargetFramework": "netstandard2.0"
+ "TargetFramework": "netstandard2.0"
}
},
{
@@ -201,28 +253,36 @@
"files": [
"Lucene.Net.Grouping/Lucene.Net.Grouping.csproj"
],
- "exclude": ["**/obj/**", "**/bin/**", "**/Lucene.Net.Test*/**"],
+ "exclude": [
+ "**/obj/**",
+ "**/bin/**",
+ "**/Lucene.Net.Test*/**"
+ ],
"src": "../../src"
- }
+ }
],
"dest": "obj/docfx/api/Lucene.Net.Grouping",
"properties": {
- "TargetFramework": "netstandard2.0"
+ "TargetFramework": "netstandard2.0"
}
- },
+ },
{
"src": [
{
"files": [
"Lucene.Net.Highlighter/Lucene.Net.Highlighter.csproj"
],
- "exclude": ["**/obj/**", "**/bin/**", "**/Lucene.Net.Test*/**"],
+ "exclude": [
+ "**/obj/**",
+ "**/bin/**",
+ "**/Lucene.Net.Test*/**"
+ ],
"src": "../../src"
}
],
"dest": "obj/docfx/api/Lucene.Net.Highlighter",
"properties": {
- "TargetFramework": "netstandard2.0"
+ "TargetFramework": "netstandard2.0"
}
},
{
@@ -231,13 +291,17 @@
"files": [
"Lucene.Net.ICU/Lucene.Net.ICU.csproj"
],
- "exclude": ["**/obj/**", "**/bin/**", "**/Lucene.Net.Test*/**"],
+ "exclude": [
+ "**/obj/**",
+ "**/bin/**",
+ "**/Lucene.Net.Test*/**"
+ ],
"src": "../../src/dotnet"
}
],
"dest": "obj/docfx/api/Lucene.Net.ICU",
"properties": {
- "TargetFramework": "netstandard2.0"
+ "TargetFramework": "netstandard2.0"
}
},
{
@@ -246,13 +310,17 @@
"files": [
"Lucene.Net.Join/Lucene.Net.Join.csproj"
],
- "exclude": ["**/obj/**", "**/bin/**", "**/Lucene.Net.Test*/**"],
+ "exclude": [
+ "**/obj/**",
+ "**/bin/**",
+ "**/Lucene.Net.Test*/**"
+ ],
"src": "../../src"
}
],
"dest": "obj/docfx/api/Lucene.Net.Join",
"properties": {
- "TargetFramework": "netstandard2.0"
+ "TargetFramework": "netstandard2.0"
}
},
{
@@ -261,28 +329,36 @@
"files": [
"Lucene.Net.Memory/Lucene.Net.Memory.csproj"
],
- "exclude": ["**/obj/**", "**/bin/**", "**/Lucene.Net.Test*/**"],
+ "exclude": [
+ "**/obj/**",
+ "**/bin/**",
+ "**/Lucene.Net.Test*/**"
+ ],
"src": "../../src"
}
],
"dest": "obj/docfx/api/Lucene.Net.Memory",
"properties": {
- "TargetFramework": "netstandard2.0"
+ "TargetFramework": "netstandard2.0"
}
- },
+ },
{
"src": [
{
"files": [
- "Lucene.Net.Misc/Lucene.Net.Misc.csproj"
+ "Lucene.Net.Misc/Lucene.Net.Misc.csproj"
+ ],
+ "exclude": [
+ "**/obj/**",
+ "**/bin/**",
+ "**/Lucene.Net.Test*/**"
],
- "exclude": ["**/obj/**", "**/bin/**", "**/Lucene.Net.Test*/**"],
"src": "../../src"
}
],
"dest": "obj/docfx/api/Lucene.Net.Misc",
"properties": {
- "TargetFramework": "netstandard2.0"
+ "TargetFramework": "netstandard2.0"
}
},
{
@@ -291,13 +367,17 @@
"files": [
"Lucene.Net.Queries/Lucene.Net.Queries.csproj"
],
- "exclude": ["**/obj/**", "**/bin/**", "**/Lucene.Net.Test*/**"],
+ "exclude": [
+ "**/obj/**",
+ "**/bin/**",
+ "**/Lucene.Net.Test*/**"
+ ],
"src": "../../src"
}
],
"dest": "obj/docfx/api/Lucene.Net.Queries",
"properties": {
- "TargetFramework": "netstandard2.0"
+ "TargetFramework": "netstandard2.0"
}
},
{
@@ -306,13 +386,17 @@
"files": [
"Lucene.Net.QueryParser/Lucene.Net.QueryParser.csproj"
],
- "exclude": ["**/obj/**", "**/bin/**", "**/Lucene.Net.Test*/**"],
+ "exclude": [
+ "**/obj/**",
+ "**/bin/**",
+ "**/Lucene.Net.Test*/**"
+ ],
"src": "../../src"
}
],
"dest": "obj/docfx/api/Lucene.Net.QueryParser",
"properties": {
- "TargetFramework": "netstandard2.0"
+ "TargetFramework": "netstandard2.0"
}
},
{
@@ -321,13 +405,17 @@
"files": [
"Lucene.Net.Replicator/Lucene.Net.Replicator.csproj"
],
- "exclude": ["**/obj/**", "**/bin/**", "**/Lucene.Net.Test*/**"],
+ "exclude": [
+ "**/obj/**",
+ "**/bin/**",
+ "**/Lucene.Net.Test*/**"
+ ],
"src": "../../src"
}
],
"dest": "obj/docfx/api/Lucene.Net.Replicator",
"properties": {
- "TargetFramework": "netstandard2.0"
+ "TargetFramework": "netstandard2.0"
}
},
{
@@ -336,13 +424,17 @@
"files": [
"Lucene.Net.Sandbox/Lucene.Net.Sandbox.csproj"
],
- "exclude": ["**/obj/**", "**/bin/**", "**/Lucene.Net.Test*/**"],
+ "exclude": [
+ "**/obj/**",
+ "**/bin/**",
+ "**/Lucene.Net.Test*/**"
+ ],
"src": "../../src"
}
],
"dest": "obj/docfx/api/Lucene.Net.Sandbox",
"properties": {
- "TargetFramework": "netstandard2.0"
+ "TargetFramework": "netstandard2.0"
}
},
{
@@ -351,13 +443,17 @@
"files": [
"Lucene.Net.Spatial/Lucene.Net.Spatial.csproj"
],
- "exclude": ["**/obj/**", "**/bin/**", "**/Lucene.Net.Test*/**"],
+ "exclude": [
+ "**/obj/**",
+ "**/bin/**",
+ "**/Lucene.Net.Test*/**"
+ ],
"src": "../../src"
}
],
"dest": "obj/docfx/api/Lucene.Net.Spatial",
"properties": {
- "TargetFramework": "netstandard2.0"
+ "TargetFramework": "netstandard2.0"
}
},
{
@@ -366,13 +462,17 @@
"files": [
"Lucene.Net.Suggest/Lucene.Net.Suggest.csproj"
],
- "exclude": ["**/obj/**", "**/bin/**", "**/Lucene.Net.Test*/**"],
+ "exclude": [
+ "**/obj/**",
+ "**/bin/**",
+ "**/Lucene.Net.Test*/**"
+ ],
"src": "../../src"
}
],
"dest": "obj/docfx/api/Lucene.Net.Suggest",
"properties": {
- "TargetFramework": "netstandard2.0"
+ "TargetFramework": "netstandard2.0"
}
},
{
@@ -381,13 +481,16 @@
"files": [
"Lucene.Net.TestFramework/Lucene.Net.TestFramework.csproj"
],
- "exclude": ["**/obj/**", "**/bin/**"],
+ "exclude": [
+ "**/obj/**",
+ "**/bin/**"
+ ],
"src": "../../src"
}
],
"dest": "obj/docfx/api/Lucene.Net.TestFramework",
"properties": {
- "TargetFramework": "netstandard2.0"
+ "TargetFramework": "netstandard2.0"
}
},
{
@@ -396,13 +499,17 @@
"files": [
"Lucene.Net.Demo/Lucene.Net.Demo.csproj"
],
- "exclude": ["**/obj/**", "**/bin/**", "**/Lucene.Net.Test*/**"],
+ "exclude": [
+ "**/obj/**",
+ "**/bin/**",
+ "**/Lucene.Net.Test*/**"
+ ],
"src": "../../src"
}
],
"dest": "obj/docfx/api/Lucene.Net.Demo",
"properties": {
- "TargetFramework": "netstandard2.0"
+ "TargetFramework": "netstandard2.0"
}
}
],
@@ -413,7 +520,7 @@
"Lucene.Net/overview.md",
"Lucene.Net.Analysis.Common/overview.md",
"Lucene.Net.Analysis.Morfologik/overview.md",
- "Lucene.Net.Analysis.OpenNLP/overview.md",
+ "Lucene.Net.Analysis.OpenNLP/overview.md",
"Lucene.Net.Highlighter/overview.md",
"Lucene.Net.Grouping/package.md",
"Lucene.Net.QueryParser/overview.md",
@@ -425,22 +532,35 @@
"dest": "api"
},
{
- "files": ["**.yml","**.md"],
+ "files": [
+ "**.yml",
+ "**.md"
+ ],
"src": "obj/docfx/api",
"dest": "api"
},
{
- "files": ["**.yml","**.md"],
+ "files": [
+ "**.yml",
+ "**.md"
+ ],
"src": "api",
"dest": "api"
},
{
- "files": ["**.md", "**.yml"],
+ "files": [
+ "**.md",
+ "**.yml"
+ ],
"src": "../../src/dotnet/tools/lucene-cli/docs",
"dest": "cli"
},
{
- "files": ["toc.yml", "*.md", "web.config"]
+ "files": [
+ "toc.yml",
+ "*.md",
+ "web.config"
+ ]
}
],
"resource": [
@@ -453,9 +573,9 @@
],
"src": "../../branding"
}
- ],
+ ],
"globalMetadata": {
- "_appTitle": "Apache Lucene.NET 4.8.0 Documentation",
+ "_appTitle": "Apache Lucene.NET 4.8.0-beta00008 Documentation",
"_disableContribution": false,
"_appFaviconPath": "logo/favicon.ico",
"_enableSearch": true,
@@ -463,13 +583,16 @@
"_appFooter": "Copyright © 2020 Licensed to the Apache Software
Foundation (ASF)",
"_gitContribute": {
"repo": "https://github.com/apache/lucenenet";,
- "branch": "docs/4.8.0-beta00007",
+ "branch": "docs/4.8.0-beta00008",
"apiSpecFolder": "websites/apidocs/apiSpec"
}
},
"overwrite": [
{
- "files": ["**/package.md","**/overview.md"],
+ "files": [
+ "**/package.md",
+ "**/overview.md"
+ ],
"src": "../../src",
"exclude": [
"Lucene.Net/overview.md",
@@ -489,7 +612,9 @@
]
},
{
- "files": ["apiSpec/**/*.md"]
+ "files": [
+ "apiSpec/**/*.md"
+ ]
}
],
"dest": "_site",
@@ -506,4 +631,4 @@
"cleanupCacheHistory": false,
"disableGitFeatures": false
}
-}
\ No newline at end of file
+}
diff --git a/websites/apidocs/docs.ps1 b/websites/apidocs/docs.ps1
index 6ac7c06..c7fc247 100644
--- a/websites/apidocs/docs.ps1
+++ b/websites/apidocs/docs.ps1
@@ -18,6 +18,9 @@
#
-----------------------------------------------------------------------------------
param (
+ [Parameter(Mandatory)]
+ [string]
+ $LuceneNetVersion,
[Parameter(Mandatory = $false)]
[int]
$ServeDocs = 1,
@@ -105,6 +108,14 @@ New-Item $PluginsFolder -type directory -force
& $msbuild $pluginSln /target:LuceneDocsPlugins "/p:OutDir=$PluginsFolder"
$DocFxJson = Join-Path -Path $ApiDocsFolder "docfx.json"
+
+# update the docjx.json file based
+$DocFxJsonContent = Get-Content $DocFxJson | ConvertFrom-Json
+$DocFxJsonContent.build.globalMetadata._appFooter = "Copyright ©
$((Get-Date).Year) Licensed to the Apache Software Foundation (ASF)"
+$DocFxJsonContent.build.globalMetadata._appTitle = "Apache Lucene.NET
$LuceneNetVersion Documentation"
+$DocFxJsonContent.build.globalMetadata._gitContribute.branch =
"docs/$LuceneNetVersion"
+$DocFxJsonContent | ConvertTo-Json -depth 100 | Set-Content $DocFxJson
+
$DocFxLog = Join-Path -Path $ApiDocsFolder "obj\docfx.log"
if ($?) {
diff --git a/websites/site/contributing/documentation.md
b/websites/site/contributing/documentation.md
index cb17705..64f52ec 100644
--- a/websites/site/contributing/documentation.md
+++ b/websites/site/contributing/documentation.md
@@ -10,12 +10,14 @@ _Details about this website and the API documentation site
and how to help contr
## Overview
-The website and the api documentation source code is found in the same Git
repository as the Lucene.Net code in the folder: `/websites/`. The site is
built with a static site generator called
[DocFx](https://dotnet.github.io/docfx/) and all of the content/pages are
created using Markdown files.
+The website and the api documentation source code is found in the same Git
repository as the Lucene.Net code in the folder: `/websites/`. The website and
documentation site is built with a static site generator called
[DocFx](https://dotnet.github.io/docfx/) and all of the content/pages are
created using Markdown files.
To submit changes for the website, create a Pull Request to the [Lucene Git
repositoriy](https://github.com/apache/lucenenet). (See
[Contributing](xref:contributing#submit-a-pull-request) for details)
## Website
+### 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:8080](http://localhost:8080).
The script has 2 optional parameters:
@@ -23,6 +25,8 @@ The script has 2 optional parameters:
* `-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 occuring with the incremental build.
+### File/folder structure
+
The file/folder structure is within `/websites/site`:
* `site.ps1` - the build script
@@ -36,13 +40,18 @@ The file/folder structure is within `/websites/site`:
## API Docs
+### 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).
-The script has 2 optional parameters:
+The script has 3 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` _(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 occuring with the incremental build.
+### File/folder structure
+
The file/folder structure is within `/websites/apidocs`:
* `docs.ps1` - the build script
@@ -51,4 +60,40 @@ The file/folder structure is within `/websites/apidocs`:
* `*.md` - the root site content such as the index and download pages
* `toc.yml` - these files determine the menu structures _(see docfx manual for
further info)_
* `tools/*` - during the build process some tools will be downloaded which are
stored here
-* `_site` - this is the exported static site that is generated
\ No newline at end of file
+* `_site` - this is the exported static site that is generated
+
+### Process overview
+
+The documentation generation is a complex process because it needs to convert
the Java Lucene project's documentation into a usable format to produce the
output Lucene.Net's documentation.
+
+The process overview is:
+
+* Use the `JavaDocToMarkdownConverter` project within the
`DocumentationTools.sln` solution to run the conversion of the Java Lucene
projects docs into a useable format for DocFx. This tool takes uses a release
tag output of the Java Lucene project as it's source to convert against the
Lucene.Net's source.
+* Run the documentation build script to produce the documentation site
+* Publish the output to the
[`lucenenet-site`](https://github.com/apache/lucenenet-site) repository into a
correpsonding named version directory and branch
+
+We don't want to manually change the converted resulting markdown files
(`.md`) because they would get overwritten again when the conversion process is
re-executed. Therefor to fix any formatting issues or customized output of the
project docs, these customizations/fixes/tweaks are built directly in to the
conversion process itself in the `JavaDocToMarkdownConverter.csproj` project.
+
+### Step by step
+
+* Checkout the Lucene.Net release tag to build the docs against
+* Execute the `./src/docs/convert.ps1` script and enter the current Lucene
version to convert from.
+ * For example, for Lucene.Net 4.8.0 we are converting from the Java Lucene
build release of
["4.8.1"](https://github.com/apache/lucene-solr/releases/tag/releases%2Flucene-solr%2F4.8.1)
so in this case enter: 4.8.1 at the prompt or call the whole script like
`./src/docs/convert.ps1 -JavaLuceneVersion 4.8.1`
+ * This script will download and extract the Java Lucene release files, build
the `DocumentationTools.sln` solution and execute the
`JavaDocToMarkdownConverter.exe`
+* Review and commit the files changed
+ * Many times there will just be whitespace changes in the files especially
if this process has been executed before for the same source/destination
version.
+ * If this is a new source/destination version there will be a **lot** of
file changes, at least one file per folder.
+ * If there are formatting issues or irregularities in the converted output
then these will need to be addressed by making changes to the conversion tool
itself `JavaDocToMarkdownConverter.csproj` (generally only needed for new major
version releases)
+* Execute the `./websites/apidocs/docs.ps1` script to build and serve the api
docs website locally for testing
+ * will serve a website on [http://localhost:8080](http://localhost:8080)
+ * It will take quite a while (approx 10 minutes) to build
+ * Example: `./websites/apidocs/docs.ps1 -LuceneNetVersion 4.8.0-beta00008`
+
+
+### Publishing the docs
+
+* Checkout the Git repo that hosts the documentation:
https://github.com/apache/lucenenet-site/tree/asf-site _(ensure you have
`asf-site` branch checked out, not `master`)_
+* Create a new folder in this repo: `/docs/[Version]`, for example:
`/docs/4.8.0-beta00008`
+* Copy the build output of the documentation site to this new folder. The
build output will be all of the files in the `/websites/apidocs/_site` in your
main lucene.net checked out Git repository.
+* Commit and push these changes
+* The new version documentation will be live. Due to the amount of new files
committed, the new files may take up to 20 minutes to become live.
\ No newline at end of file
