Github user NightOwl888 commented on the issue:
https://github.com/apache/lucenenet/pull/206
I use the Releases section to find the commit to use, as these are frozen
points in time. This is a little tricky because the core library was ported
from
[4.8.0](https://github.com/apache/lucene-solr/releases/tag/releases%2Flucene-solr%2F4.8.0)
and some other sections (particularly the Analysis modules) were ported over
from
[4.8.1](https://github.com/apache/lucene-solr/releases/tag/releases%2Flucene-solr%2F4.8.1).
So, I would suggest creating a throwaway branch and using 4.8.0 to generate
the docs, do a commit, and then do it again with 4.8.1 to see if there are any
notable documentation changes in 4.8.1 (outside of core/Lucene.Net). Since the
APIs remained the same between 4.8.0 and 4.8.1, I suspect the Analysis docs
haven't changed in any significant way.
Alternatively, skip the test and just use 4.8.0, since that is what we are
claiming this to be a port of. Ideally, we use the tool on each commit point in
the future that is ported to re-generate the docs and then go back through them
manually to copy/edit the code samples and custom sections that were added in
the previous port.
------------------------
One thing that will tie this together is for the Powershell command that
generates the docs to accept the version number as a parameter. This will allow
the documentation links to GitHub to be generated pointing to the release that
we are generating so it can be fully automated. The
[JavaDocToMarkdownConverter](https://github.com/apache/lucenenet/tree/master/src/dotnet/tools/JavaDocToMarkdownConverter)
is setup to generate the links with a `{tag}` token that represents the
version number, which would be replaced when the docs are built.
Ideally, we would add a task to the [build
script](https://github.com/apache/lucenenet/blob/a3a12967b250e8e7e5f623f0ba7572ec64f479ac/build/build.ps1)
and an option to the [build.bat
script](https://github.com/apache/lucenenet/blob/a3a12967b250e8e7e5f623f0ba7572ec64f479ac/build.bat)
(and the [place where it is autogenerated for a
release](https://github.com/apache/lucenenet/blob/a3a12967b250e8e7e5f623f0ba7572ec64f479ac/build/build.ps1#L430-L488))
for the documentation to be generated by end users that download the [latest
release](http://www.apache.org/dyn/closer.cgi/lucenenet/), when a user clones
the repo, or by TeamCity when each release is generated (which calls the
build.ps1 script directly).
We could potentially use some automation to overwrite the main Lucene.Net
website and add a new subfolder for each version of docs right from the
[Lucene.Net
Release](https://teamcity.jetbrains.com/project.html?projectId=LuceneNet_PortableBuilds&tab=projectOverview)
step.
But the point is, all of this will need a version number passed as a
parameter to stay in sync (including during prerelease builds).
-------------------------
Which leads into another point - officially, the Apache releases are these
signed zip files, the NuGet packages are just for convenience. The zip files
are hosted on [mirrors](http://www.apache.org/dyn/closer.cgi/lucenenet/) so the
user can download from the nearest server.
If you are going to be taking on the Lucene.Net web site project as well,
every Apache example I have seen includes a separate [download CGI
file](https://lucenenet.apache.org/download.cgi) that includes some HTML/CSS
formatting to match the rest of the site and some logic to show the nearest
download location to the end user by default. I don't know for sure if there is
an alternative to using a CGI script for that voodoo to happen.
[Here is an
email](http://mail-archives.apache.org/mod_mbox/lucenenet-dev/201708.mbox/%[email protected]%3E)
thread that had some discussion about the site, including the location of the
source code of the current site.
Ideally the new site will have 2 download links - one to the release on
NuGet.org and the other to the mirrors with the official Apache release.
---
