lucenenet-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From GitBox <...@apache.org>
Subject [GitHub] [lucenenet] Shazwazza commented on issue #282: Docs - Build/Deploy Automation
Date Mon, 01 Jun 2020 03:23:09 GMT

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



Mime
View raw message