Website/API Documentation

[Shad Storhaug <sh...@shadstorhaug.com>]

Hi Shannon,

I have just released the docs and updated the website for 4.8.0-beta00015 and it mostly went smoothly.

Release Notes
===========

I have also updated the Release Procedure with the instructions for adding the Release Notes to the web site, since this has been what I have been doing for the last 3 releases. Please review and let me know if you spot anything that was left out or could use clarification/correction.

https://lucenenet.apache.org/contributing/make-release.html

This document is getting really long, but I discovered that if we can base the Release pipeline on whoever clicked the "Run Pipeline" button, we can probably store the key (or even a sub-key?) in Azure DevOps secure files so we can automate the signing step for whoever clicked that button.

https://joemiller.me/2019/07/signing-releases-with-a-gpg-project-key/

Of course, we should check for a non-expired key at the beginning of the process and fail the build early if a valid signing key doesn't exist for the user. Once that is automated, many of the other steps following it could be automated, as well.

DocFx Version
===========

Running the build for the website locally, even after building with the -Clean switch, I am getting a different version of DocFx than what is in the build on Azure DevOps.

https://dev.azure.com/shazwazza/Lucene.Net%20Build%20Test/_build?definitionId=1&_a=summary

Local version: docfx 2.56.6.0
Server version: docfx 2.58.0.0

Errors
=====

I got the following errors intermittently at least 3 times during the API docs build. Strangely, they don't seem to be affecting the output. But, could these perhaps be due to being behind a couple of versions?

Building site output for F:\Projects\lucenenet\websites\apidocs\docfx.core.json...
[21-10-30 01:11:26.705]Error:[BuildCore.Build Document.CompilePhaseHandlerWithIncremental.ManagedReferenceDocumentProcessor.Build.BuildManagedReferenceDocument](obj/docfx/api/core/Lucene.Net.Index.IndexWriter.IndexReaderWarmer.yml)Markup failed: Index was out of range. Must be non-negative and less than the size of the collection.
Parameter name: chunkLength.


Build failed.
[21-10-30 01:11:28.544]Error:[BuildCore.Build Document.CompilePhaseHandlerWithIncremental.ManagedReferenceDocumentProcessor.Build.BuildManagedReferenceDocument](obj/docfx/api/core/Lucene.Net.Index.IndexWriter.IndexReaderWarmer.yml)Markup failed: Index was out of range. Must be non-negative and less than the size of the collection.
Parameter name: chunkLength.
        0 Warning(s)
        1 Error(s)

Building site output for F:\Projects\lucenenet\websites\apidocs\docfx.spatial.json...
[21-10-30 01:07:26.830]Error:[BuildCore.Build Document.CompilePhaseHandlerWithIncremental.ManagedReferenceDocumentProcessor.Build.BuildManagedReferenceDocument](obj/docfx/api/spatial/Lucene.Net.Spatial.Prefix.PrefixTreeStrategy.yml)Markup failed: Index was out of range. Must be non-negative and less than the size of the collection.
Parameter name: chunkLength.


Build failed.
[21-10-30 01:07:27.215]Error:[BuildCore.Build Document.CompilePhaseHandlerWithIncremental.ManagedReferenceDocumentProcessor.Build.BuildManagedReferenceDocument](obj/docfx/api/spatial/Lucene.Net.Spatial.Prefix.PrefixTreeStrategy.yml)Markup failed: Index was out of range. Must be non-negative and less than the size of the collection.
Parameter name: chunkLength.
        0 Warning(s)
        1 Error(s)

API Documentation Navigation
=========================

I noticed that other than on the home page of the documentation site, the only place that you can tell which version of documentation you are looking at is in the URL.

Also, when clicking documentation on the home page, it first takes you to the documentation.md page where you must select the version to view. It seems to me this could be simplified:


  1.  User clicks "Documentation", it takes them to the home page of the most recent version.
  2.  Somewhere on the page of each of the API docs (maybe on the right just below "Improve this page"), it could display the current version of the docs you are looking at and have a way to switch to an older version.
  3.  Ideally, at least within the same major version, the user could navigate directly to the same page for the desired version without having to go back to the version selection page.
     *   For versions where the page doesn't have the same URL, it gets a "page not found". Maybe we could redirect to the documentation.md for the current version in that case.
  4.  There should also be an option where the user can click "See all versions" to go to the current documentation.md page so they can easily get to the 3x and 2x versions.

TeamCity is one example of a product that has many different versions of docs online at once. It doesn't look like they have a way to navigate to the same page on another version, though. If that is too complex, we could probably omit that, also. But they also put a warning on the legacy documentation to let users know they aren't viewing the latest version with a link back to the version selection page.

https://www.jetbrains.com/help/teamcity/multinode-setup.html

Thoughts?



Thanks,

Shad Storhaug (NightOwl888)

Project Chairperson - Apache Lucene.NET