Documentation: Tidy up of Lucene.Net.Join

[stevetemple]

1. Fixing broken links referring to Lucene.Net.Search.Join. Namespace is Lucene.Net.Join in the other docs.
2. Breaking what looks like it was supposed to be bullets into bullets rather than a single bullet
3. Making code sample render as code sample

[Shazwazza]

Hi @stevetemple thanks for this. The way that the docs are produced goes through quite a process of converting the docs from the java source to the .net source through various processes of transformation. In order to get this fixed we'll need to adjust the transformation process to make sure this is output correctly otherwise these changes will just get overwritten next time we build the docs.

That said, this is a great start for me to know what needs changing and to document how this process works. For this fix, we'll need to adjust this project: https://github.com/apache/lucenenet/tree/master/src/dotnet/tools/JavaDocToMarkdownConverter

which is the tool that is run against the java source (zip output) https://github.com/apache/lucene-solr/releases/tag/releases%2Flucene-solr%2F4.8.0

[stevetemple]

Oh wow, I thought there was something odd about the docs.

This just got more fun... will take a look in the morning

[stevetemple]

Have created another PR #233 that should fix the namespaces that 404

[Shazwazza]

Great stuff @stevetemple , should this PR be closed then?

[stevetemple]

@Shazwazza I think there are two more things I've spotted which would be nice to get working before closing this as matching the output of the automated conversion:

1. New paras appear to be starting with a space which messes up formatting following the list
2. The code samples aren't getting tripple back ticked

Now we're on latest Html2Markdown I think they will be trivial to solve

[Shazwazza]

OK, i uploaded the build output of the docs but i don't think it fixed the issues expected but maybe i did something wrong. I'll need to run locally and test too but won't be able to till next week.

[stevetemple]

Oh, where did you upload them?

[Shazwazza]

Just to the main docs site https://lucenenetdocs.azurewebsites.net/

[stevetemple]

Oh that looks disappointly unchanged, even the namespace update hasn't happened

[Shazwazza]

yeah i think i must have deployed it incorrectly, i'll test, etc... this week

[Shazwazza]

@stevetemple ah it was because i just didn't re-run the docs migrator and commit the changes 🤦‍♂ I've done that now and things look much better. I've deployed those changes to the site https://lucenenetdocs.azurewebsites.net/

[stevetemple]

That looks a look a lot better. Any idea how best to tackle method names being different casing between java and C# getTopGroups -> GetTopGroups etc.

[NightOwl888]

Just FYI, the original idea behind the Javadoc to Markdown converter was to clean up the "namespace" documents to a level of around 80-90% and then do the rest of the work manually. Generally speaking, that would not include the code samples. The idea was that it would only be run one time per Lucene port to Lucene.NET manually, not be put into a pipeline.

That said, if you manage to get it to get it to port the documents to 100%, my hat's off to you. The code samples in the "namespace" documents are probably simple enough to do automation on by setting up specific rules. Short of that, we could probably rig up something with a hash code to alert us to when the code changes in the pipeline so they can be manually dealt with.

Of course, in the code examples we should try to put our best foot forward. We have managed to take advantage of some of .NET's type initializers to significantly improve the readability/reduce verbosity of the code (for an example, the "Add to the Index" section of the home page), and we should try to make our documents reflect those changes rather than just a carbon copy of the Java code.

Speaking of which, the "Construct a Query" section on the home page could also be simplified from:

// search with a phrase
var phrase = new MultiPhraseQuery();
phrase.Add(new Term("favoritePhrase", "brown"));
phrase.Add(new Term("favoritePhrase", "fox"));

to:

// search with a phrase
var phrase = new MultiPhraseQuery
{
    new Term("favoritePhrase", "brown"),
    new Term("favoritePhrase", "fox")
};

[stevetemple]

I think we could get this pretty close. The code samples being the most difficult part.

I agree that at some point it would make sense to say this is as good as it's going to get and switch to manual updates then a notification of something changed and put in a queue to review.

[Shazwazza]

Hi all, i'll close this PR as many things have been resolved in the #235 changes and many of those changes have already been applied to the live docs site. I'll try to get some final changes in to #325 and merge and start a new one with any pending changes. I have ideas for the code snippets too, i think we can still get quite far with the automation side of things before we have to start thinking of modifying the docs directly.