lucenenet-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Shazwazza <...@git.apache.org>
Subject [GitHub] lucenenet issue #206: API Doc site generator using DocFx script
Date Fri, 30 Jun 2017 04:39:19 GMT
Github user Shazwazza commented on the issue:

    https://github.com/apache/lucenenet/pull/206
  
    Hi all,
    
    Here's some feedback on many of the above questions/comments:
    
    I've pushed some updates to this PR which:
    
    * Fixed up a couple of cref's
    * Updated to use latest docfx v2.17.x release (be sure to delete the /tools folder) to
get the latest version when running the ps1 script. Unfortunatey upgrading to the very latest
docfx 2.19.2 causes build errors. I also checked that 2.18.x also causes these build errors.
I'm putting together a bug report for this now. I has to do with some YAML parsing errors
and things like "quoted scalar" and "orphaned high surrogate" which sound fun ;) 
    * Adds some comments to the ps1 script about where other docs live and potentially somehow
scraping/automating fetching these docs
    * Update the home page of the docs to mimic https://lucene.apache.org/core/4_8_0/, I've
just copied the HTML, then removed the html/body tags and replaced the header tags with Markdown
header tags so they are parsed correctly by DocFx to create the side menu. The links throughout
this document will need to be updated since they still point to the lucene.apache.org links.
I've done this to show that HTML markup works happily side by side and inline with Markdown
with DocFx which will probably make it easier to scrape docs.
    * Adds a landing page in the API Docs section which is a copy of this page: https://github.com/apache/lucene-solr/blob/branch_4x/lucene/core/src/java/overview.html
(links would need to be fixed), this file is committed to /api/index.md
    * Adds example docs and table of contents: /api/search/highlight which includes the docs
taken from the package.html files (i.e. https://github.com/apache/lucene-solr/blob/releases/lucene-solr/4.8.0/lucene/highlighter/src/java/org/apache/lucene/search/highlight/package.html)

    * Updated the header menu to point to custom documentation articles and also the API docs
    
    I cannot figure out why docfx is complaining about System cref's such as `Invalid cref
value "T:IDictionary{string, string}"`, i think it has to do with a missing config `externalReference`
which is now obsoleted so hoping that the newer docfx version fixes this once i get it building.
    
    If you wish to test this setup without waiting for the entire metadata for all classes
to be created, you can update the /docfx.json file metadata/src/files section from `"**.csproj"`
 to `"**/Lucene.Net.csproj"`  (which will just generate the API docs for that particular project),
or just clear that out entirely if you just want to build the non-api docs for testing. 
    
    Currently DocFx does not support the namespace style docuementation that Sandcastle used
to support, there's an open issue for that here: https://github.com/dotnet/docfx/issues/952
So for namespace style documentation such as https://github.com/apache/lucene-solr/blob/releases/lucene-solr/4.8.0/lucene/highlighter/src/java/org/apache/lucene/search/highlight/package.html
we would currently have to host these as documentation articles. Currently I've put documentation
articles in the /docs folder but it's possible to have any number of different articles folders
if required.
    
    As for changing how the namespaces are shown on the left hand side and ordering by more
important ones, this could be achieved by modifying the generated /api/toc.yml file after
it is built. This file is autogenerated by docfx when it's building the API docs. As far as
I can tell one way to do this would be with a custom Post Processor: https://dotnet.github.io/docfx/tutorial/howto_add_a_customized_post_processor.html
but OOTB I don't think this is possible with standard configuration.
    
    I'm not really sure what we can do about the .NET Standard vs .NET Framework, there is
some mention of this in this issue: https://github.com/dotnet/docfx/issues/1518 which apparently
is fixed in this PR https://github.com/dotnet/docfx/pull/1549 . I will just need to figure
out exactly what all this means and what the options are. 
    
    For token replacement, i think this could also be achieved with a Post Processor in one
way or another https://dotnet.github.io/docfx/tutorial/howto_add_a_customized_post_processor.html,
though i did see this feature in later release notes: https://github.com/dotnet/docfx/issues/1737

    
    There's quite a lot of docs on docfx here http://dotnet.github.io/docfx/tutorial/docfx_getting_started.html

    
    Hope this answers a few of your questions. I'll keep researching into the new docfx versions,
what support it has and why we can't use it currently.


---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---

Mime
View raw message