API Documentation Build Issues

[NightOwl888]

Building the documentation isn't going as smoothly as it used to. I ended up having to manually patch up the Lucene.Net.Codecs namespace page and the changes link, and had to try several builds before I got one to succeed.

Table of Contents

1. - Build Errors
2. - Codecs Override File Intermittent
3. - Changes Link

Build Errors

Building the docs never seems to work the first time. I tried:

1. Building the solution in Release mode before building
2. Closing Visual Studio before building
3. Using the -Clean switch

None of these seem to help. The documentation seems to build nearly to the end, and then one of the projects (a different one each time) will get an IndexOutOfRangeException. Here are my last 2 errors:

Building site output for F:\Projects\lucenenet\websites\apidocs\docfx.classification.json...
[21-11-23 05:38:35.601]Error:[BuildCore.Build Document.CompilePhaseHandlerWithIncremental.ManagedReferenceDocumentProcessor.Build.BuildManagedReferenceDocument](obj/docfx/api/classification/Lucene.Net.Classification.KNearestNeighborClassifier.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-11-23 05:38:35.888]Error:[BuildCore.Build Document.CompilePhaseHandlerWithIncremental.ManagedReferenceDocumentProcessor.Build.BuildManagedReferenceDocument](obj/docfx/api/classification/Lucene.Net.Classification.KNearestNeighborClassifier.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)
Get-Content : Cannot find path 'F:\Projects\lucenenet\websites\apidocs\_site\api\classification\xrefmap.yml' because it does not
exist.
At F:\Projects\lucenenet\websites\apidocs\docs.ps1:234 char:20
+         $xrefMap = Get-Content $xrefFile -Raw
+                    ~~~~~~~~~~~~~~~~~~~~~~~~~~
    + CategoryInfo          : ObjectNotFound: (F:\Projects\luc...ion\xrefmap.yml:String) [Get-Content], ItemNotFoundException
    + FullyQualifiedErrorId : PathNotFound,Microsoft.PowerShell.Commands.GetContentCommand

Building site output for F:\Projects\lucenenet\websites\apidocs\docfx.core.json...
[21-11-23 05:54:02.376]Error:[BuildCore.Build Document.CompilePhaseHandlerWithIncremental.ManagedReferenceDocumentProcessor.Build.BuildManagedReferenceDocument](obj/docfx/api/core/Lucene.Net.Search.Similarities.Distribution.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-11-23 05:54:03.902]Error:[BuildCore.Build Document.CompilePhaseHandlerWithIncremental.ManagedReferenceDocumentProcessor.Build.BuildManagedReferenceDocument](obj/docfx/api/core/Lucene.Net.Search.Similarities.Distribution.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)
Get-Content : Cannot find path 'F:\Projects\lucenenet\websites\apidocs\_site\api\core\xrefmap.yml' because it does not exist.
At F:\Projects\lucenenet\websites\apidocs\docs.ps1:234 char:20
+         $xrefMap = Get-Content $xrefFile -Raw
+                    ~~~~~~~~~~~~~~~~~~~~~~~~~~
    + CategoryInfo          : ObjectNotFound: (F:\Projects\luc...ore\xrefmap.yml:String) [Get-Content], ItemNotFoundException
    + FullyQualifiedErrorId : PathNotFound,Microsoft.PowerShell.Commands.GetContentCommand

Codecs Override File Intermittent

The file at https://lucenenet.apache.org/docs/4.8.0-beta00015/api/core/Lucene.Net.Codecs.html doesn't always override. Out of about 6-7 builds I did locally, I only saw it successfully override once, and that was in a debug build.

I scoured the commit history to see if I could find anything that could explain this, but nothing seems to have changed recently except the version of DocFx. Of course, I may have unintentionally uninstalled a dependency from my system when clearing disk space (for example, in VS2017 I cleared out all of the workloads except for Web and Desktop).

Changes Link

The changes link on the API Docs home page doesn't replace the environment variable for the GitHub URL. As a result, the link is broken. I fixed it manually on beta-00015, but beta-00014 is still broken: https://lucenenet.apache.org/docs/4.8.0-beta00014/

[Shazwazza]

Will start looking at this again soon - and get automation working. Think the docs automation will now be fixed by infra too 🤞

[Shazwazza]

I think a lot of this comes due to being half way through automation and not completing it but we had to merge to master to get the other parts working for the site. Anyways, i'll investigate and hopefully automate it all.

[NightOwl888]

I think a lot of this comes due to being half way through automation and not completing it but we had to merge to master to get the other parts working for the site. Anyways, i'll investigate and hopefully automate it all.

Actually, I did the entire build locally this time. So, it is quite possible I am missing a dependency. But that doesn't explain why it is intermittent.

But I agree, putting it all in an automation pipeline would take all of those issues out of the equation.

[paulirwin]

This should be resolved with #961 for sure, if not changes before this. Closing this issue.