lucenenet-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From NightOwl888 <...@git.apache.org>
Subject [GitHub] lucenenet pull request #206: API Doc site generator using DocFx script
Date Fri, 30 Jun 2017 09:50:01 GMT
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 infrastructure@apache.org or file a JIRA ticket
with INFRA.
---

Mime
View raw message