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 Wed, 03 Jun 2020 00:09:23 GMT

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


   Hi @NightOwl888 thanks for having a peek through the source too. We are already using extensions
for DocFx, that is what our `LuceneDocsPlugins` csproj is all about and that is using MEF
to extend the functionality. I also discovered that `IAssemblySymbol` is what sets the UID
based on the namespace but that is a Roslyn object and not part of docfx and as far as I can
tell none of the `ManagedReference` functionality that puts together the API docs isn't using
MEF for composing itself though it is used in other places like generating `Conception` (i.e.
non API docs) . I didn't see that the `IExtractor` was public, perhaps there's a way to override
that but because MEF isn't used in composing this part of the app I'm just not sure. There
was a single extension point I did find for the `ManagedReference` which are part of `ExtractMetadataOptions.RoslynExtensionMethods`
and these extensions are discovered by `RoslynIntermediateMetadataExtractor.GetAllExtensionMethodsFromCompilation`
though i didn't spend much more time to see if this can work.
   
   The mini site approach seems to be the preferred approach to multi-project systems. That
is what Microsoft are doing (MS docs are built with docfx with probably a lot of customization
and knowledge of work arounds), for example: https://docs.microsoft.com/en-us/dotnet/api/?view=aspnetcore-3.1
this is their landing page and each links off to a 'sub site' which is essentially what I'm
doing now. Have also chatted with another project and their usage of docfx and that is what
they do as well. 
   
   I've discovered more extensibility too which I'm now using. For each subsite an xrefdoc.yml
is generated which is a list of cross reference links. Then for each build of each site and
main site you can feed in external xrefdoc.yml so that cross references work between projects.
I'm trialing this now but there will still be some interesting 'gotchas' because there will
still be overlapping namespace UIDs which I still need to figure out. There's also something
called a pre-processor which is done at the template building level via nodejs and you can
completely override all metadata for each page including namespace information, etc.. .but
for some reason i think the UID is protected. I still haven't fully pursued this entirely
but it's on my list of tools that we can use.
   
   
   
   
   
   


----------------------------------------------------------------
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