Lucene - Core
  1. Lucene - Core
  2. LUCENE-4007

many versioned documents could/should be in javadocs instead.

    Details

    • Type: Task Task
    • Status: Closed
    • Priority: Major Major
    • Resolution: Fixed
    • Affects Version/s: 4.0-ALPHA
    • Fix Version/s: 4.0-ALPHA
    • Component/s: general/website
    • Labels:
      None
    • Lucene Fields:
      New

      Description

      Looking at our forrested site, and trying to think about how we could move our versioned site
      away from it, I think as a first step we should look at what really needs to be there.

      I think it easily becomes out of date and we don't have good centralized documentation since
      stuff is split between javadocs and forrest.

      Couldn't queryparsersyntax.xml simply be in the overview/package for the queryparser?
      We could just link to that page from the forrest docs menu, then we could link to the syntax from
      other places in the javadocs.
      Furthermore, in that case we could link to other queryparser impls documentations (e.g. complexphrase)
      so it would probably be more useful.

      demo/demo2.xml could just be overview for the demo contrib? currently that one is useless:
      https://builds.apache.org/job/Lucene-trunk/javadoc/demo/index.html

      scoring.xml could be added to the package documentation of search or similarities or somewhere that
      makes more sense? currently its "almost javadocs" already, except harder to validate none of these
      links are actually out of date: my best bet is a ton of them already are!

      i'll leave fileformats.xml aside for now, but with many different codec implementations its something
      to think about for later too.

      1. LUCENE-4007.patch
        1.74 MB
        Uwe Schindler
      2. LUCENE-4007.patch
        1.74 MB
        Uwe Schindler
      3. LUCENE-4007.patch
        130 kB
        Uwe Schindler

        Activity

        Hide
        Uwe Schindler added a comment -

        Committed Revision: 1328748

        Show
        Uwe Schindler added a comment - Committed Revision: 1328748
        Hide
        Robert Muir added a comment -

        +1!!!! this is exciting, as i feel actually motivated to improve these docs... the previous
        system was too high a barrier to get anything done.

        Show
        Robert Muir added a comment - +1!!!! this is exciting, as i feel actually motivated to improve these docs... the previous system was too high a barrier to get anything done.
        Hide
        Uwe Schindler added a comment -

        Fixed locally. I will commit that asap, so we can proceed with nuking the scoring.html and fix all remaining documentation files.

        Show
        Uwe Schindler added a comment - Fixed locally. I will commit that asap, so we can proceed with nuking the scoring.html and fix all remaining documentation files.
        Hide
        Robert Muir added a comment -

        I got it from http://lucene.apache.org/images/lucene_green_300.gif

        I think we should nuke the old 'ant docs' task.
        instead 'ant package' should depend on 'documentation' instead of 'docs,javadocs,changes2html,...'

        then packaging i think is fine.

        Show
        Robert Muir added a comment - I got it from http://lucene.apache.org/images/lucene_green_300.gif I think we should nuke the old 'ant docs' task. instead 'ant package' should depend on 'documentation' instead of 'docs,javadocs,changes2html,...' then packaging i think is fine.
        Hide
        Uwe Schindler added a comment -

        Ah and also place in lucene/site/html the file lucene_green_300.gif (its somewhere placed under the forrest source or on homepage)

        Show
        Uwe Schindler added a comment - Ah and also place in lucene/site/html the file lucene_green_300.gif (its somewhere placed under the forrest source or on homepage)
        Hide
        Uwe Schindler added a comment -

        Patch without forrest delete.

        You have to svn rm: lucene/site/build, lucene/site/src and lucene/site/forrest.properties

        Show
        Uwe Schindler added a comment - Patch without forrest delete. You have to svn rm: lucene/site/build, lucene/site/src and lucene/site/forrest.properties
        Hide
        Uwe Schindler added a comment -

        New patch against rev. 1328746

        Show
        Uwe Schindler added a comment - New patch against rev. 1328746
        Hide
        Uwe Schindler added a comment -

        Fixed, too

        Show
        Uwe Schindler added a comment - Fixed, too
        Hide
        Robert Muir added a comment -

        OK two more:
        define-lucene-javadoc-url-SNAPSHOT
        and
        define-lucene-javddoc-url-release

        These would be the url links (if we nuke api, then the website will reflect it).

        So if we fix these 3 things then solr will work.

        Show
        Robert Muir added a comment - OK two more: define-lucene-javadoc-url-SNAPSHOT and define-lucene-javddoc-url-release These would be the url links (if we nuke api, then the website will reflect it). So if we fix these 3 things then solr will work.
        Hide
        Uwe Schindler added a comment -

        OK, fixed locally.

        Show
        Uwe Schindler added a comment - OK, fixed locally.
        Hide
        Robert Muir added a comment -

        I think its just that one 'lucenedocs' property.

        Show
        Robert Muir added a comment - I think its just that one 'lucenedocs' property.
        Hide
        Robert Muir added a comment -

        I just glanced, no testing yet... but if we change javadocs root to be build/docs (instead of build/docs/api), then
        we must adjust the variable in solr/common-build to fit:

        cd solr, find -name "*-build.xml" | xargs grep "docs/api"

        Show
        Robert Muir added a comment - I just glanced, no testing yet... but if we change javadocs root to be build/docs (instead of build/docs/api), then we must adjust the variable in solr/common-build to fit: cd solr, find -name "*-build.xml" | xargs grep "docs/api"
        Hide
        Uwe Schindler added a comment -

        Patch applying the chainsaw to the forrest:

        • The documentation root is now build/docs/index.html, which is created by XSL transformation
        • Query Parser syntax was moved to the javadocs of o.a.l.queryparser.classic overview.html
        • Scoring howto is still outside javadocs, but de-forrested by the carpenter.
        • Same for demo1/demo2 howto pages
        • The documentation including javadocs is created by "ant documentation"
        • Javadocs are now directly per module under docs/, no api folder inbetween.
        Show
        Uwe Schindler added a comment - Patch applying the chainsaw to the forrest: The documentation root is now build/docs/index.html, which is created by XSL transformation Query Parser syntax was moved to the javadocs of o.a.l.queryparser.classic overview.html Scoring howto is still outside javadocs, but de-forrested by the carpenter. Same for demo1/demo2 howto pages The documentation including javadocs is created by "ant documentation" Javadocs are now directly per module under docs/, no api folder inbetween.
        Hide
        Uwe Schindler added a comment -

        That was the idea, the XSLT would contain the whole html, in addition to the root link list. I can take that issue and prepare patch.

        Show
        Uwe Schindler added a comment - That was the idea, the XSLT would contain the whole html, in addition to the root link list. I can take that issue and prepare patch.
        Hide
        Robert Muir added a comment -

        Oh thats a nice idea: though it would be cool if maybe it didnt generate the whole root index file but possibly added to it?

        I think it would be nice if we could have a little top-level information besides just the list of modules, that links to certain "key" documents like queryparser syntax, fileformats, facet userguide, demo instructions, analysis overview, scoring (similar to today, but ideally better).

        But maybe your xslt could also incorporate this too?

        Show
        Robert Muir added a comment - Oh thats a nice idea: though it would be cool if maybe it didnt generate the whole root index file but possibly added to it? I think it would be nice if we could have a little top-level information besides just the list of modules, that links to certain "key" documents like queryparser syntax, fileformats, facet userguide, demo instructions, analysis overview, scoring (similar to today, but ideally better). But maybe your xslt could also incorporate this too?
        Hide
        Uwe Schindler added a comment -

        Another idea, we should nuke the whole versioned docs. Like for the facet module, additional Html can be placed in source tree (folder doc-files or like that, take facet as example) and linked from overview page. The ant-generated index html could be improved to be the root index file. I am working on that (I'll make it a XSLT at the.moment...).

        This way, the whole site docs are generaded by the javadocs task.

        Show
        Uwe Schindler added a comment - Another idea, we should nuke the whole versioned docs. Like for the facet module, additional Html can be placed in source tree (folder doc-files or like that, take facet as example) and linked from overview page. The ant-generated index html could be improved to be the root index file. I am working on that (I'll make it a XSLT at the.moment...). This way, the whole site docs are generaded by the javadocs task.
        Hide
        Robert Muir added a comment -

        Thats my opinion too Uwe: i think we should nuke the whole forrest and just have
        links (maybe with fileformats as a plain html page for now).

        I just wanted to get the issue open for discussion, if its controversial, at least
        we can take it on a case by case basis for each one of these files and cut down
        one tree at a time...

        Show
        Robert Muir added a comment - Thats my opinion too Uwe: i think we should nuke the whole forrest and just have links (maybe with fileformats as a plain html page for now). I just wanted to get the issue open for discussion, if its controversial, at least we can take it on a case by case basis for each one of these files and cut down one tree at a time...
        Hide
        Uwe Schindler added a comment -

        I would make the current forrest site a plain old html with some links to the javadocs and a plain html fileformat page.

        Show
        Uwe Schindler added a comment - I would make the current forrest site a plain old html with some links to the javadocs and a plain html fileformat page.
        Hide
        Uwe Schindler added a comment -

        Nice idea. I would put the syntax inside the java package overview itsself and not into the module overview. As we have multiple parsers, we should separate their syntaxes.

        Show
        Uwe Schindler added a comment - Nice idea. I would put the syntax inside the java package overview itsself and not into the module overview. As we have multiple parsers, we should separate their syntaxes.
        Hide
        Robert Muir added a comment -

        Even if we don't decide to do this, we could at least enhance
        the forrest site by linking to a few key javadocs pages.

        Take a look at the "getting started" page (which is mostly empty)
        compared to http://lucene.apache.org/core/3_6_0/api/core/overview-summary.html#overview_description

        https://builds.apache.org/job/Lucene-trunk/javadoc/core/org/apache/lucene/analysis/package-summary.html#package_description
        is also a good page to introduce the analysis api,

        same goes with Similarity and a few other javadocs.

        Basically in my opinion, the "versioned site" could just link to some of these pages (easy way
        to chainsaw the forrest), but if we don't want to go that route we can at least enhance it to point
        to some of the really good docs we already have under javadocs so its not so sparse.

        Show
        Robert Muir added a comment - Even if we don't decide to do this, we could at least enhance the forrest site by linking to a few key javadocs pages. Take a look at the "getting started" page (which is mostly empty) compared to http://lucene.apache.org/core/3_6_0/api/core/overview-summary.html#overview_description https://builds.apache.org/job/Lucene-trunk/javadoc/core/org/apache/lucene/analysis/package-summary.html#package_description is also a good page to introduce the analysis api, same goes with Similarity and a few other javadocs. Basically in my opinion, the "versioned site" could just link to some of these pages (easy way to chainsaw the forrest), but if we don't want to go that route we can at least enhance it to point to some of the really good docs we already have under javadocs so its not so sparse.

          People

          • Assignee:
            Uwe Schindler
            Reporter:
            Robert Muir
          • Votes:
            0 Vote for this issue
            Watchers:
            0 Start watching this issue

            Dates

            • Created:
              Updated:
              Resolved:

              Development