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 infrastruct...@apache.org or file a JIRA ticket
with INFRA.
---

Reply via email to