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 Thu, 28 May 2020 15:42:30 GMT

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


   For the short term of fixing this codec issue - and there are others similar:
   
   The issue is that the way lucene classes/namespaces are structures overlap with each other.
This also why we have the breadcrumb issue. Because of this we get overlapping `uid` values
where a `uid` is the unique name of a document. For example, the UID for the codec namespace
within lucene 'core' package is `uid: Lucene.Net.Codecs` and the UID for the codec namespace
within lucene's 'codec' package is `uid: Lucene.Net.Codecs` and again this overlaps with the
code package in the test-framework: `uid: Lucene.Net.Codecs`
   
   The reason this didn't behave this way in the previous docs version was because the converter
wasn't picking up all of the namespace files and including them in the conversion which meant
a lot of docs were missing, however it meant because we were missing docs we probably didn't
have `uid` collisions. 
   
   There's a couple ways to fix this:
   
   * Change the uid values to include the orig package name like `core/Lucene.Net.Codecs`
(or similar). 
   * Change the way the docs are structure - similar to how the javadocs are - which would
basically be that each 'package' has it's own separate 'mini site'
   
   I'll try to the first one now since it's easier, but both have pros/cons, i actually think
the second option might be safest but i'm unsure how it will work just yet. I'll just to have
give these a shot.
   
   > Any thoughts on how to add additional documents? For example, it might be best to
separate ASP.NET Core configuration examples from command line examples or other application
frameworks.
   
   There's a few ways to do examples. DocFx supports 'overwrite files' like i mentioned and
this is already configured but i haven't played around with it much yet. Basically it allows
you to add metadata to any conceptual (i.e. code) document. So for example, in c# you might
have a class but you didn't add `/// <example> put code here </example>` inline
in your code. Well you can add this metadata to that class via overwrite files. There can
be a number of examples per class or method too. So that's one way, but depends on where you
want the docs or examples to live. Each 'namespace' or 'class' page can have any amount of
information on it before it starts listing members, etc... 
   There's a tabbed markdown feature https://dotnet.github.io/docfx/spec/docfx_flavored_markdown.html#tabbed-content
which might work for varying frameworks, but i'm unsure if that would work for overwrite files
for /// <example> style code but maybe. 
   I guess there's a lot of ways to do things so would need a concrete example of what you
'want' to do .
   
   
   
   https://dotnet.github.io/docfx/tutorial/intro_overwrite_files.html
   


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