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 [email protected] or file a JIRA ticket
with INFRA.
---
