Github user NightOwl888 commented on the issue:
https://github.com/apache/lucenenet/pull/206
@Shazwazza
Looking good.
I like the drill down packages, although what I had in mind was a bit
simpler than that - basically I was thinking to link over to the page and
autofill the search box so it would filter for the namespace. Then the user
would have a way to remove the filter just by deleting the text. But don't
change it on my account, as long is it is functional its all good.
### Release
I am getting really close to finishing up the release, and it is looking
like we will be able to start the release vote as early as next week. The only
thing left on the list above is to package up the the CLI utility and the API
docs. There are a few failing tests I am tracking down and a few other tasks to
do, but nothing very time consuming. I think the most time consuming task will
be manual cleanup of the overview/package documents.
If you have a chance this weekend would be ideal to try to get this to the
point where we can do our first docs release. I don't expect it to be perfect
and there can be additional pull requests after this one, but lets just try to
make it functional.
Do note for a release, we need to add an Apache license header to every
file (source, config, project, and documentation). There is a tool called
[RAT](https://creadur.apache.org/rat/) that can automate that step. Take care
not to do it on the test files, as we had an issue on the last release after
changing some of them.
### JavaDoc to Markdown Conversion Tool/Package Docs
I have committed the [JavaDocToMarkdownConverter
tool](https://github.com/apache/lucenenet/tree/master/src/dotnet/tools/JavaDocToMarkdownConverter)
and have also done a preliminary conversion (with no manual changes) so you
can work out how to consume the documents. There are 244 markdown docs, but I
am not sure we need the one liners. If you can't work out what to do with them,
perhaps we should just setup the generator to automatically delete documents
that are less than 900 bytes, which would eliminate them if they don't have any
useful content.
I ended up changing the names from readme.md back to overview.md and
package.md because in some places they would collide due to being written to
the same directory.
### Namespace Links
I still haven't worked out what to do about namespace links. Hopefully once
you consume them with DocFx, you can work out and provide me with a better idea
how to convert them - it would be nice to automate that part as much as
possible before doing the manual cleanup work.
### Code Links
I followed the approach in the links you sent using `[link
text](xref:uid)`. Let me know if that works, as I have not tested with DocFx.
> There seems to be a few converters out there but not sure if they work
specifically for Confluence WIKI format. I feel pretty dumb asking this but how
the heck do you see the WIKI format source for this?
https://cwiki.apache.org/confluence/display/LUCENENET/Lucene.Net
For that, you would need special permissions (I think Prescott would be the
one to ask about that). But the info on the WIKI is so far out of date I am not
sure it is much use at this point. What specifically do you want to do with it?
I tried to copy and paste it here, but apparently the text is formatted
using JavaScript and when copied it just comes out plain text with no
formatting - not even breaks between paragraphs.
### New .csproj Format
Do note I have also upgraded us to the new .csproj format (and moved some
projects to a new dotnet folder). I noticed you are referencing some of these
files, and I hope the new format isn't a blocker for DocFx. Basically, they no
longer contain any of the file references - all files are loaded by default and
they are manually excluded them when you don't want them.
The solution will also only load in Visual Studio 2017 (15.3 or higher).
### Build
I thought I saw a comment above about what part of the build this is going
in, but I don't see it now. Basically, we will be adding this to the Lucene.Net
Release task in TeamCity
(https://teamcity.jetbrains.com/project.html?projectId=LuceneNet_PortableBuilds&tab=projectOverview).
I think the first time out we can just do the documentation build and
deployment manually, which will give me some idea how to setup the build. But
one thing I do know for sure is that we will need to add a parameter to the
powershell build script to pass in the Git tag that corresponds to the current
build, and this value should replace `{tag}` in the repo links. Keep in mind,
we may need to do this from the regular API docs as well.
### .gitignore
Still having an issue. You have ignored the `apidocs` folder, but there is
another folder that gets generated in the root directory named `api` that is
not ignored.
### Lucene.Net.Cli
This should be excluded from the API docs since it is not consumable. But
we will want to include the usage documentation under
`src\dotnet\tools\lucene-cli\docs\`.
### Lucene.Net.ICU
This is kind of an oddball package and is probably going to be tough to do
the documentation for. Basically, the code files were left in their original
locations, but they are linked to and compiled into this project from several
other projects. If this turns out to be too challenging to create the
documentation, don't worry about it for this release - it is the most buggy
part of Lucene.Net for the time being, anyway.
---
