Github user NightOwl888 commented on a diff in the pull request:
https://github.com/apache/lucenenet/pull/206#discussion_r125003467
--- Diff: apidocs/docs.ps1 ---
@@ -49,10 +49,17 @@ If ($FileExists -eq $False) {
if ($Clean -eq 1) {
Remove-Item (Join-Path -Path $ApiDocsFolder "obj\*") -recurse -force
-ErrorAction SilentlyContinue
Remove-Item (Join-Path -Path $ApiDocsFolder "obj") -force -ErrorAction
SilentlyContinue
- Remove-Item (Join-Path -Path $ApiDocsFolder "api\*") -recurse -force
-ErrorAction SilentlyContinue
- Remove-Item (Join-Path -Path $ApiDocsFolder "api") -force -ErrorAction
SilentlyContinue
+ Remove-Item (Join-Path -Path $ApiDocsFolder "api\*") -exclude "*.md"
-recurse -force -ErrorAction SilentlyContinue
+ ##Remove-Item (Join-Path -Path $ApiDocsFolder "api") -force
-ErrorAction SilentlyContinue
}
+# NOTE: There's a ton of Lucene docs that we want to copy and re-format.
I'm not sure if we can really automate this
+# in a great way since the docs seem to be in many places, for example:
+# Home page -
https://github.com/apache/lucene-solr/blob/branch_4x/lucene/site/xsl/index.xsl
+# Wiki docs -
https://wiki.apache.org/lucene-java/FrontPage?action=show&redirect=FrontPageEN
- not sure where the source is for this
+# Html pages - Example:
https://github.com/apache/lucene-solr/blob/releases/lucene-solr/4.8.0/lucene/highlighter/src/java/org/apache/lucene/search/highlight/package.html
- these seem to be throughout the source
+# For these ones, could we go fetch them and
download all *.html files from Git?
+
--- End diff --
The folders follow a specific convention in both Java and and .NET, so
making a tool to do most of this is possible. The main thing to address is the
fact that there are code links and namespace links in many of those documents
(see https://lucene.apache.org/core/4_8_0/core/index.html), so we need a clear
idea about how to translate org.apache.lucene.analysis to the correct namespace
HTML link and org.apache.lucene.analysis.Analyzer to the correct class HTML
link, etc.
BTW - I noticed that in the Java source this file is named overview.html,
so it must be processed in some way to convert it to index.html. Perhaps we can
just change the namespaces to be correct for .NET with the converter tool and
then make the actual hyperlinking part of the build process for the docs?
There is still a lot of manual cleanup to be done to convert the code
samples, and verify accuracy of the information for .NET, but we should be able
to automate a big chunk of the conversion if we have conventions to follow.
I'm torn between making a custom folder for the converted documents to live
in or keeping it close to the original location. Since we cannot make automate
100% of the conversion process, it would probably be best to keep the original
file locations as much as possible so when upgrading all of the `.cs` documents
these are not missed as part of the upgrade.
---
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.
---
