lucenenet-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From NightOwl888 <...@git.apache.org>
Subject [GitHub] lucenenet issue #206: API Doc site generator using DocFx script
Date Sat, 05 Aug 2017 16:40:42 GMT
Github user NightOwl888 commented on the issue:

    https://github.com/apache/lucenenet/pull/206
  
    @Shazwazza 
    
    I finally got a chance to look at this today. A fine docs site this is becoming. 
    
    Now it is becoming a bit more clear how to build a tool to convert all of those HTML files.
I will start working on a tool to take care of that, starting with the `overview.html` pages,
and then work out how to get those "namespace documents", the `package.html` pages. There
are a few simple changes that can be done to convert many of the code comments completely
(namely changing the first letter of every method or field name to upper case and moving opening
curly brackets from the end of a line to the beginning of the following line), and then they
will need manual review (which I can drop a token in to search for so this can be done by
multiple people over a period of time).
    
    There will probably need to be several revisions of the tool before we actually commit
to a manual starting point, though.
    
    > I've added a WIKI section to show how that can be done, I've copied the HTML content
from the current wiki, I only did the home page, getting started and mail group pages as examples
and update the links between them. The html could/should be formatted to markdown (not sure
how the source of the current wiki is?) but that is optional but the links between pages should
be updated to markdowns since that's much easier to generate the links.
    
    Unfortunately, the format of the WIKI is not markdown. [Here is the documentation](https://confluence.atlassian.com/doc/confluence-wiki-markup-251003035.html)
for the Confluence WIKI markup format. Maybe a converter for this format to markdown exists,
though...?
    
    > > 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.
    
    > Normally when faced with post-build issues such as these I either overwrite the contents
of the file by [generating it in the Powershell script](https://github.com/apache/lucenenet/blob/master/build/build.ps1#L304-L351)
or use the Powershell script to update the contents of the file, depending on how much of
the file I need control over.
    
    > But I wasn't referring to the order of them so much as the depth. For example, it
would be best if we had a link to `Lucene.Net.Analysis` in the TOC that when clicked expanded
the `Lucene.Net.Analysis.Ar`, `Lucene.Net.Analysis.Bg`, etc. instead of having all of the
Analysis.Common hierarchy in the initial view that loads.
    
    A thought occurred to me how we might handle this. Is there such a thing as a filter that
can be applied to the TOC so that only the part from a single .NET assembly appears at a time?
Then when for example, you click on "analyzers-common", and you get a view of the index page
on the right and a TOC on the left that is filtered for that NuGet package, similar to [the
original](https://lucene.apache.org/core/4_8_0/analyzers-common/index.html). I don't think
we need the "packages" section on the upper left, though - that doesn't seem to work for .NET.
But having the filtered TOC here would make it easy to drill down/search the rest of Analysis.Common
without going through the sea of other NuGet package documentation. And maybe there could
be a way to remove the filter to see everything again.
    
    ### Minor Issue
    
    The `api` folder is not currently in `.gitignore`, so the `.yml` documents all appear
as uncommitted files.


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