[GitHub] [lucenenet] Shazwazza commented on issue #282: Docs - Build/Deploy Automation

[GitBox <gi...@apache.org>]

Shazwazza commented on issue #282:
URL: https://github.com/apache/lucenenet/issues/282#issuecomment-636592141


   I've spent quite a lot of time over the weekend investigating options for this issue. Going with the option of creating 'mini sites' has shortcomings as well because the xref won't resolve between sites since they would be compiled separately from each other. I haven't had enough time to see what extending the xref behavior requires and hope that might be possible. I've looked into potentially keeping our structure so that xref behavior 'just works' and was hoping to change the behavior of docfx to be in control over how the api docs are produced. I've tried creating a researching any type of docfx plugin I can find and trawling through the source code to try to figure out if the API builder can be extended and unfortunately I'm coming up short of a hopeful solution. I've asked questions on their gitter channel as well as re-asking them on GH but have received no response. From what I can tell in the docfx code, the API docs and metadata for them are generated directly from using Roslyn which is done in [this class](https://github.com/dotnet/docfx/blob/dev/src/Microsoft.DocAsCode.Metadata.ManagedReference.Roslyn/Visitors/VisitorHelper.cs) and the process [starts here](https://github.com/dotnet/docfx/blob/dev/src/Microsoft.DocAsCode.Metadata.ManagedReference.Roslyn/ExtractMetadata/RoslynIntermediateMetadataExtractor.cs) but none of it is extendable that I can see and the API docs extraction doesn't use their regular pluggable techniques. The only possible extendable place I can see is some obscure [roslyn extension methods](https://github.com/dotnet/docfx/blob/54c9e0593acde8aac9450592ad8fe7268b226d19/src/Microsoft.DocAsCode.Metadata.ManagedReference/ExtractMetadataWorker.cs#L291) but all of this is entirely undocumented so I don't even know if i want to attempt to go down that avenue. Ideally, if we could 'just' change the root namespace UID for each 'package' to be specific to that 'package' then all classes/namespaces in that tree would inherit that base UID which in turn would make unique xref's. But I do not see this as a possibility in docfx. So am left with 2 options:
   
   * Pursue the 'mini site' method which will require additional research into figuring out how that can work since while somehow allowing cross xref's between sites
   * Try modifying docfx core to see if it can produce what we need with changing the base namespace UID's, though i think that's going to consume a lot of research time too and might not end up being 'possible'
   
   That's the status so far, i wish there was an actual documented way to do this.  I'll spend a bit more time this week to see what I can find and hopefully come up with some proof of concept.
   
   
   
   
   


----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

For queries about this service, please contact Infrastructure at:
users@infra.apache.org