This is an automated email from the ASF dual-hosted git repository.
shazwazza pushed a commit to branch asf-site
in repository https://gitbox.apache.org/repos/asf/lucenenet-site.git
The following commit(s) were added to refs/heads/asf-site by this push:
new 4a74f62 Deploys updated docs for docs and links for new release and
docs
4a74f62 is described below
commit 4a74f62add00cf43f68f7e7875e865e7913e2afe
Author: Shannon <[email protected]>
AuthorDate: Wed May 27 15:54:15 2020 +1000
Deploys updated docs for docs and links for new release and docs
---
contributing/documentation.html | 70 ++++++++++++++++++++++++++++++++++-
docs.html | 1 +
download/version-4.8.0-beta00007.html | 4 ++
download/version-4.8.0-beta00008.html | 7 +++-
manifest.json | 16 ++++----
5 files changed, 86 insertions(+), 12 deletions(-)
diff --git a/contributing/documentation.html b/contributing/documentation.html
index fd0a21f..3c0f00c 100644
--- a/contributing/documentation.html
+++ b/contributing/documentation.html
@@ -76,15 +76,17 @@
<hr>
<p><em>Details about this website and the API documentation site and how to
help contribute to them</em></p>
<h2 id="overview">Overview</h2>
-<p>The website and the api documentation source code is found in the same Git
repository as the Lucene.Net code in the folder: <code>/websites/</code>. The
site is built with a static site generator called <a
href="https://dotnet.github.io/docfx/";>DocFx</a> and all of the content/pages
are created using Markdown files.</p>
+<p>The website and the api documentation source code is found in the same Git
repository as the Lucene.Net code in the folder: <code>/websites/</code>. The
website and documentation site is built with a static site generator called <a
href="https://dotnet.github.io/docfx/";>DocFx</a> and all of the content/pages
are created using Markdown files.</p>
<p>To submit changes for the website, create a Pull Request to the <a
href="https://github.com/apache/lucenenet";>Lucene Git repositoriy</a>. (See <a
class="xref" href="index.html#submit-a-pull-request">Contributing</a> for
details)</p>
<h2 id="website">Website</h2>
+<h3 id="build-script">Build script</h3>
<p>To build the website and run it on your machine, run the powershell script:
<code>/websites/site/site.ps1</code>. You don't have to pass any parameters in
and it will build the site and host it at <a
href="http://localhost:8080";>http://localhost:8080</a>.</p>
<p>The script has 2 optional parameters:</p>
<ul>
<li><code>-ServeDocs</code> <em>(default is 1)</em> The value of
<code>1</code> means it will build the docs and host the site, if
<code>0</code> is specified, it will build the static site to be hosted
elsewhere.</li>
<li><code>-Clean</code> <em>(default is 0)</em> The value of <code>1</code>
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.</li>
</ul>
+<h3 id="filefolder-structure">File/folder structure</h3>
<p>The file/folder structure is within <code>/websites/site</code>:</p>
<ul>
<li><code>site.ps1</code> - the build script</li>
@@ -96,13 +98,24 @@
<li><code>tools/*</code> - during the build process some tools will be
downloaded which are stored here</li>
<li><code>_site</code> - this is the exported static site that is
generated</li>
</ul>
+<h3 id="deploy-the-website">Deploy the website</h3>
+<ul>
+<li>The website is deployed via git</li>
+<li>Checkout the Git repo that hosts the documentation: <a
href="https://github.com/apache/lucenenet-site/tree/asf-site";>https://github.com/apache/lucenenet-site/tree/asf-site</a>
<em>(ensure you have <code>asf-site</code> branch checked out, not
<code>master</code>)</em></li>
+<li>Copy the build output of the website to the root. The build output will be
all of the files in the <code>/websites/site/_site</code> in your main
lucene.net checked out Git repository.</li>
+<li>Commit and push these changes</li>
+<li>The new version of the website will be live. If the amount of new files
committed is large, the new files may take some time to become live.</li>
+</ul>
<h2 id="api-docs">API Docs</h2>
+<h3 id="build-script-1">Build script</h3>
<p>To build the api docs and run it on your machine, run the powershell
script: <code>/websites/apidocs/docs.ps1</code>. You don't have to pass any
parameters in and it will build the site and host it at <a
href="http://localhost:8080";>http://localhost:8080</a>.</p>
-<p>The script has 2 optional parameters:</p>
+<p>The script has 3 parameters:</p>
<ul>
+<li><code>-LuceneNetVersion</code> <em>(mandatory)</em> This is the Lucene.Net
version including pre-release information that is being built. For example:
<code>4.8.0-beta00008</code>. <em>(This value will correspond to the folder and
branch name where the docs get hosted, see below)</em></li>
<li><code>-ServeDocs</code> <em>(default is 1)</em> The value of
<code>1</code> means it will build the docs and host the site, if
<code>0</code> is specified, it will build the static site to be hosted
elsewhere.</li>
<li><code>-Clean</code> <em>(default is 0)</em> The value of <code>1</code>
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.</li>
</ul>
+<h3 id="filefolder-structure-1">File/folder structure</h3>
<p>The file/folder structure is within <code>/websites/apidocs</code>:</p>
<ul>
<li><code>docs.ps1</code> - the build script</li>
@@ -113,6 +126,59 @@
<li><code>tools/*</code> - during the build process some tools will be
downloaded which are stored here</li>
<li><code>_site</code> - this is the exported static site that is
generated</li>
</ul>
+<h3 id="process-overview">Process overview</h3>
+<p>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.</p>
+<p>The process overview is:</p>
+<ul>
+<li>Use the <code>JavaDocToMarkdownConverter</code> project within the
<code>DocumentationTools.sln</code> 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.</li>
+<li>Run the documentation build script to produce the documentation site</li>
+<li>Publish the output to the <a
href="https://github.com/apache/lucenenet-site";><code>lucenenet-site</code></a>
repository into a correpsonding named version directory</li>
+</ul>
+<p>We don't want to manually change the converted resulting markdown files
(<code>.md</code>) 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
<code>JavaDocToMarkdownConverter.csproj</code> project.</p>
+<h3 id="building-the-docs">Building the docs</h3>
+<ul>
+<li>Checkout the Lucene.Net release tag to build the docs against</li>
+<li>Execute the <code>./src/docs/convert.ps1</code> script and enter the
current Lucene version to convert from.
+<ul>
+<li>For example, for Lucene.Net 4.8.0 we are converting from the Java Lucene
build release of <a
href="https://github.com/apache/lucene-solr/releases/tag/releases%2Flucene-solr%2F4.8.1";>"4.8.1"</a>
so in this case enter: 4.8.1 at the prompt or call the whole script like
<code>./src/docs/convert.ps1 -JavaLuceneVersion 4.8.1</code></li>
+<li>This script will download and extract the Java Lucene release files, build
the <code>DocumentationTools.sln</code> solution and execute the
<code>JavaDocToMarkdownConverter.exe</code></li>
+</ul>
+</li>
+<li>Review and commit the files changed
+<ul>
+<li>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.</li>
+<li>If this is a new source/destination version there will be a
<strong>lot</strong> of file changes, at least one file per folder.</li>
+<li>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 <code>JavaDocToMarkdownConverter.csproj</code> (generally only needed
for new major version releases)</li>
+</ul>
+</li>
+<li>Execute the <code>./websites/apidocs/docs.ps1</code> script to build and
serve the api docs website locally for testing.
+<ul>
+<li>Example: <code>./websites/apidocs/docs.ps1 -LuceneNetVersion
4.8.0-beta00008</code></li>
+<li>will serve a website on <a
href="http://localhost:8080";>http://localhost:8080</a></li>
+<li>It will take quite a while (approx 10 minutes) to build</li>
+</ul>
+</li>
+</ul>
+<h3 id="publishing-the-docs">Publishing the docs</h3>
+<ul>
+<li>Checkout the Git repo that hosts the documentation: <a
href="https://github.com/apache/lucenenet-site/tree/asf-site";>https://github.com/apache/lucenenet-site/tree/asf-site</a>
<em>(ensure you have <code>asf-site</code> branch checked out, not
<code>master</code>)</em></li>
+<li>Create a new folder in this repo: <code>/docs/[Version]</code>, for
example: <code>/docs/4.8.0-beta00008</code></li>
+<li>Copy the build output of the documentation site to this new folder. The
build output will be all of the files in the
<code>/websites/apidocs/_site</code> in your main lucene.net checked out Git
repository.</li>
+<li>Commit and push these changes</li>
+<li>The new version documentation will be live. Due to the amount of new files
committed, the new files may take up to 60 minutes to become live.</li>
+<li>Next the website needs updating which is a manual process currently:
+<ul>
+<li>In the <code>/websites/site/download</code> folder there should be a
document per release. It's normally fine to copy the document of the latest
release for the same major version. For a new major version some modifications
may be needed.</li>
+<li>Ensure the correct version number is listed in the header and the nuget
download snippet.</li>
+<li>Update the <code>Status</code> and <code>Released</code> heading
information.</li>
+<li>Ensure the download links are correct.</li>
+<li>Update the <code>/websites/site/download/toc.yml</code> file to include a
reference to the new page which should maintain descending version order.</li>
+<li>Update the <code>/websites/site/docs.md</code> file and add a link to the
new documentation for the current version which should maintain descending
version order.</li>
+<li><a href="#website">Build the website</a> and test locally, then deploy the
changes</li>
+</ul>
+</li>
+<li>Once the website is committed/pushed, the last step is to create a named
branch on the main <a
href="https://github.com/apache/lucenenet";><code>lucenenet</code></a>
repository with the name: <code>docs/[Version]</code>, for example
<code>docs/4.8.0-beta00008</code> based on commit of the latest (if any)
changes made to the docs in the <code>lucenenet</code> repository on the main
branch. This branch is used for linking to on the API docs "Improve this
Doc" button.</li>
+</ul>
</article>
</div>
diff --git a/docs.html b/docs.html
index b1affcc..931a382 100644
--- a/docs.html
+++ b/docs.html
@@ -62,6 +62,7 @@
<h2 id="lucene-480">Lucene 4.8.0</h2>
<p>The API docs are slightly different between versions, each one is listed
below:</p>
<ul>
+<li><a
href="https://lucenenet.apache.org/docs/4.8.0-beta00008/";>4.8.0-beta00008</a></li>
<li><a
href="https://lucenenet.apache.org/docs/4.8.0-beta00007/";>4.8.0-beta00007</a></li>
<li><a
href="https://lucenenet.apache.org/docs/4.8.0-beta00005/";>4.8.0-beta00001 ->
4.8.0-beta00006</a></li>
</ul>
diff --git a/download/version-4.8.0-beta00007.html
b/download/version-4.8.0-beta00007.html
index a9dc113..4c39622 100644
--- a/download/version-4.8.0-beta00007.html
+++ b/download/version-4.8.0-beta00007.html
@@ -77,6 +77,10 @@
<h2 id="lucene-480-beta00007">Lucene 4.8.0-beta00007</h2>
<p><em>Status:</em> <strong><code>Beta</code></strong></p>
<p><em>Released:</em> <code>2019-12-29</code></p>
+<ul>
+<li>Source release: <strong><a
href="https://www.apache.org/dyn/closer.lua/lucenenet/4.8.0-beta00007/Apache-Lucene.Net-4.8.0-beta00007.src.zip";>Lucene.Net-4.8.0-beta00007.src.zip</a></strong>
[<a
href="https://downloads.apache.org/lucenenet/4.8.0-beta00007/Apache-Lucene.Net-4.8.0-beta00007.src.zip.asc";>PGP</a>]
[<a
href="https://downloads.apache.org/lucenenet/4.8.0-beta00007/Apache-Lucene.Net-4.8.0-beta00007.src.zip.sha512";>SHA512</a>]</li>
+<li>Binary release: <strong><a
href="https://www.apache.org/dyn/closer.lua/lucenenet/4.8.0-beta00007/Apache-Lucene.Net-4.8.0-beta00007.bin.zip";>Lucene.Net-4.8.0-beta00007.src.zip</a></strong>
[<a
href="https://downloads.apache.org/lucenenet/4.8.0-beta00007/Apache-Lucene.Net-4.8.0-beta00007.bin.zip.asc";>PGP</a>]
[<a
href="https://downloads.apache.org/lucenenet/4.8.0-beta00007/Apache-Lucene.Net-4.8.0-beta00007.bin.zip.sha512";>SHA512</a>]</li>
+</ul>
<div class="nuget-well" style="text-align:left;">
PM> Install-Package Lucene.Net -Version 4.8.0-beta00007
</div>
diff --git a/download/version-4.8.0-beta00008.html
b/download/version-4.8.0-beta00008.html
index 5b8f48a..ff88c8e 100644
--- a/download/version-4.8.0-beta00008.html
+++ b/download/version-4.8.0-beta00008.html
@@ -77,11 +77,14 @@
<h2 id="lucene-480-beta00008">Lucene 4.8.0-beta00008</h2>
<p><em>Status:</em> <strong><code>Beta</code></strong></p>
<p><em>Released:</em> <code>2020-05-05</code></p>
+<ul>
+<li>Source release: <strong><a
href="https://www.apache.org/dyn/closer.lua/lucenenet/4.8.0-beta00008/Apache-Lucene.Net-4.8.0-beta00008.src.zip";>Lucene.Net-4.8.0-beta00008.src.zip</a></strong>
[<a
href="https://downloads.apache.org/lucenenet/4.8.0-beta00008/Apache-Lucene.Net-4.8.0-beta00008.src.zip.asc";>PGP</a>]
[<a
href="https://downloads.apache.org/lucenenet/4.8.0-beta00008/Apache-Lucene.Net-4.8.0-beta00008.src.zip.sha512";>SHA512</a>]</li>
+<li>Binary release: <strong><a
href="https://www.apache.org/dyn/closer.lua/lucenenet/4.8.0-beta00008/Apache-Lucene.Net-4.8.0-beta00008.bin.zip";>Lucene.Net-4.8.0-beta00008.src.zip</a></strong>
[<a
href="https://downloads.apache.org/lucenenet/4.8.0-beta00008/Apache-Lucene.Net-4.8.0-beta00008.bin.zip.asc";>PGP</a>]
[<a
href="https://downloads.apache.org/lucenenet/4.8.0-beta00008/Apache-Lucene.Net-4.8.0-beta00008.bin.zip.sha512";>SHA512</a>]</li>
+<li><a
href="https://github.com/apache/lucenenet/releases/tag/Lucene.Net_4_8_0_beta00008";>Change
log</a></li>
+</ul>
<div class="nuget-well" style="text-align:left;">
PM> Install-Package Lucene.Net -Version 4.8.0-beta00008
</div>
-<h2 id="release-notes">Release notes</h2>
-<p><a
href="https://github.com/apache/lucenenet/releases/tag/Lucene.Net_4_8_0_beta00008";>https://github.com/apache/lucenenet/releases/tag/Lucene.Net_4_8_0_beta00008</a></p>
<h3 id="source-code">Source code</h3>
<ul>
<li><a href="https://github.com/apache/lucenenet";>Git Repository</a></li>
diff --git a/manifest.json b/manifest.json
index 9d2c2c4..53e70c6 100644
--- a/manifest.json
+++ b/manifest.json
@@ -65,10 +65,10 @@
"output": {
".html": {
"relative_path": "contributing/documentation.html",
- "hash": "/lxVA3mFgR+peeftZ9fg8w=="
+ "hash": "sr9DtSR+oHr+I9hflRS7kw=="
}
},
- "is_incremental": true,
+ "is_incremental": false,
"version": ""
},
{
@@ -80,7 +80,7 @@
"hash": "L5F7bB0yVZt+WTCPNICyyA=="
}
},
- "is_incremental": true,
+ "is_incremental": false,
"version": ""
},
{
@@ -173,7 +173,7 @@
"output": {
".html": {
"relative_path": "docs.html",
- "hash": "H5rCwWvclAI2bEHHGHk+eA=="
+ "hash": "3qh45t74IM0nOyudXHf8rA=="
}
},
"is_incremental": true,
@@ -188,7 +188,7 @@
"hash": "5FRWCTdfMlKgzpLiErkm0w=="
}
},
- "is_incremental": false,
+ "is_incremental": true,
"version": ""
},
{
@@ -233,7 +233,7 @@
"output": {
".html": {
"relative_path": "download/version-4.8.0-beta00007.html",
- "hash": "0riUtWLfrQXCjD3U+OciMQ=="
+ "hash": "wVHfm/sRR1oi9cTxRdYF0w=="
}
},
"is_incremental": true,
@@ -245,10 +245,10 @@
"output": {
".html": {
"relative_path": "download/version-4.8.0-beta00008.html",
- "hash": "IGY5slfyOqdmQJbe1b9FCQ=="
+ "hash": "iHifEvMireZX2FwhV6yeuw=="
}
},
- "is_incremental": false,
+ "is_incremental": true,
"version": ""
},
{
