lucenenet-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From NightOwl888 <...@git.apache.org>
Subject [GitHub] lucenenet issue #206: API Doc site generator using DocFx script
Date Fri, 01 Jun 2018 08:01:39 GMT
Github user NightOwl888 commented on the issue:

    https://github.com/apache/lucenenet/pull/206
  
    I use the Releases section to find the commit to use, as these are frozen points in time.
This is a little tricky because the core library was ported from [4.8.0](https://github.com/apache/lucene-solr/releases/tag/releases%2Flucene-solr%2F4.8.0)
and some other sections (particularly the Analysis modules) were ported over from [4.8.1](https://github.com/apache/lucene-solr/releases/tag/releases%2Flucene-solr%2F4.8.1).
    
    So, I would suggest creating a throwaway branch and using 4.8.0 to generate the docs,
do a commit, and then do it again with 4.8.1 to see if there are any notable documentation
changes in 4.8.1 (outside of core/Lucene.Net). Since the APIs remained the same between 4.8.0
and 4.8.1, I suspect the Analysis docs haven't changed in any significant way.
    
    Alternatively, skip the test and just use 4.8.0, since that is what we are claiming this
to be a port of. Ideally, we use the tool on each commit point in the future that is ported
to re-generate the docs and then go back through them manually to copy/edit the code samples
and custom sections that were added in the previous port.
    
    ------------------------
    
    One thing that will tie this together is for the Powershell command that generates the
docs to accept the version number as a parameter. This will allow the documentation links
to GitHub to be generated pointing to the release that we are generating so it can be fully
automated. The [JavaDocToMarkdownConverter](https://github.com/apache/lucenenet/tree/master/src/dotnet/tools/JavaDocToMarkdownConverter)
is setup to generate the links with a `{tag}` token that represents the version number, which
would be replaced when the docs are built.
    
    Ideally, we would add a task to the [build script](https://github.com/apache/lucenenet/blob/a3a12967b250e8e7e5f623f0ba7572ec64f479ac/build/build.ps1)
and an option to the [build.bat script](https://github.com/apache/lucenenet/blob/a3a12967b250e8e7e5f623f0ba7572ec64f479ac/build.bat)

     (and the [place where it is autogenerated for a release](https://github.com/apache/lucenenet/blob/a3a12967b250e8e7e5f623f0ba7572ec64f479ac/build/build.ps1#L430-L488))
for the documentation to be generated by end users that download the [latest release](http://www.apache.org/dyn/closer.cgi/lucenenet/),
when a user clones the repo, or by TeamCity when each release is generated (which calls the
build.ps1 script directly).
    
    We could potentially use some automation to overwrite the main Lucene.Net website and
add a new subfolder for each version of docs right from the [Lucene.Net Release](https://teamcity.jetbrains.com/project.html?projectId=LuceneNet_PortableBuilds&tab=projectOverview)
step.
    
    But the point is, all of this will need a version number passed as a parameter to stay
in sync (including during prerelease builds).
    
    -------------------------
    
    Which leads into another point - officially, the Apache releases are these signed zip
files, the NuGet packages are just for convenience. The zip files are hosted on [mirrors](http://www.apache.org/dyn/closer.cgi/lucenenet/)
so the user can download from the nearest server.
    
    If you are going to be taking on the Lucene.Net web site project as well, every Apache
example I have seen includes a separate [download CGI file](https://lucenenet.apache.org/download.cgi)
that includes some HTML/CSS formatting to match the rest of the site and some logic to show
the nearest download location to the end user by default. I don't know for sure if there is
an alternative to using a CGI script for that voodoo to happen.
    
    [Here is an email](http://mail-archives.apache.org/mod_mbox/lucenenet-dev/201708.mbox/%3C000001d30daf$0ad426f0$207c74d0$@webuniverse.net%3E)
thread that had some discussion about the site, including the location of the source code
of the current site.
    
    Ideally the new site will have 2 download links - one to the release on NuGet.org and
the other to the mirrors with the official Apache release.
    
    
    
    



---

Mime
View raw message