Lucene Java Site docs

• Key: LUCENE-707
• Type: Improvement
• Status: Closed
• Resolution: Fixed
• Priority: Minor
• Assignee: Erik Hatcher
• Reporter: Grant Ingersoll
• Component/s: Website

Description

It would be really nice if the Java site docs where consistent with the rest of the Lucene family (namely, with navigation tabs, etc.) so that one can easily go between Nutch, Hadoop, etc.

Comments

[Grant Ingersoll]

First draft of Forrest (http://forrest.apache.org) based Lucene website. You need Forrest 0.7 to build it. I will try to post a link on my website or the Lucene website for people to view.

I copied SOLR's structure (and Hadoop's, it seems) and then brought in the files from the xdocs directory. I then gave all these files a facelift for Forrest.

I went through all the pages, but I may have missed something so, I am looking for some other eyes to help spot errors.

One thing that is missing is the link to the Nightly version of the website(in the left menu, under Site Versions). I am waiting to get setup on zones.apache.org per Doug's email. Once I get that figured out, I will put in the proper link.

Note that the xdocs directory gets deleted. All significant documentation related files are safely moved to the src/site directory structure.

I can put a prebuilt version on people.apache.org, but I am not sure if Apache would like me to post the URL for consumption to the public. Does anyone know if it is alright to publish a website such as this on people.apache.org under my user account? Doug? If it is OK, I will send out a URL for people to view, otherwise download the patch and give it a try.

If I don't hear back by next Friday or so (the 10th), I will commit this patch and make this the official Lucene website.

[Grant Ingersoll]

I found a bunch of issues with the previous patch (thanks to Steve Rowe) so I am withdrawing it. Will post a fixed version soon.

[Grant Ingersoll]

I think I have ironed out the issues. I am not going to submit a patch, just yet, instead I ask that people go review the site at http://people.apache.org/~gsingers/site/ (note: the breadcrumbs at the top reflect that it is deployed on my site and will be different when on the real site)

Here is a summary of what will be in the patch/commit when we are ready:
1. Move xdocs etc. into Forrest common structure under src/site (as is the case w/ SOLR and Hadoop)
2. xdocs and docs directory are deleted
3. site directory is cleaned out and the new site is put in there
4. New site update instructions will be the same as: http://wiki.apache.org/solr/Website_Update_HOWTO

The "Site Versions" section will eventually have a link to a nightly build of the site (as per issue 708) but we are having some infrastructure issues w/ setting this up for now, but that part will be coming soon and I am going to decouple that bug from this one so as to not hold up this one.

Please let me know what you think, but stick to layout problems and introduced errors (i.e. write up a different bug for errors in the documentation that already exist).

Thanks!
Grant

[Grant Ingersoll]

Any last comments on the new site? I am going to commit these changes within the week (per the 4 items laid out in the previous comments) and put up the new site. Most likely will do so Sunday night or Monday.

To review/comment, see http://people.apache.org/~gsingers/site/

[Yonik Seeley]

> New site update instructions will be the same as: http://wiki.apache.org/solr/Website_Update_HOWTO

We might want a generic version that various subprojects can use.
Doug had some comments regarding that in the past:

Doug wrote:
> We should probably add something like that for the other sites, or
> generically for all sites and link to it.
>
> One clarification might be to change "go to" to "connect to" or, better
> yet, give the 'cd solr/src/site' command line. Probably each command
> line should be given in full, to avoid confusion, as in
> http://wiki.apache.org/solr/HowToContribute.

[Doug Cutting]

The recently clarified Apache release policy at http://www.apache.org/dev/release.html states that we should not link to or otherwise refer to nightly builds as releases. Any links to nightly builds should be from a part of the site that's clearly for developers and not for end users.

[Otis Gospodnetic]

Grant, you should remove links to lucene4C (dead), and add links to Lucene.NET in the Incubator.
I see 2 Lucene logos up at the top. I think the smaller one o the left should be the ASF feather.

[Otis Gospodnetic]

Oh, and don't we want tabs for individual sub-projects at the top, like on lucene.apache.org today?

[Grant Ingersoll]

The other projects are listed under others. I pretty much copied SOLR's layout and then moved Lucene Java XDocs into the site structure, so I think they are at least consistent with the other sub-projects.

Also, not sure about the logos. The other sites have our "original" logo on the left, as the Lucene brand, and then their logo (SOLR, Hadoop) as the larger icon. Lucene Java has always used the green Lucene logo, so I wasn't sure what to do, so I had it up there twice. But I like the feather idea, so I have changed that

On Releases, Steve Rowe suggested that I change the menu link to be "Downloads", which I have done (I also added a info on how to get the source code)

Otis, thanks for the Lucene4C info. I wasn't sure on it's status, so I left it as is. I have now removed it.

Yonik, I agree the website update info should be made generic, but that is beyond my control for coordinating across projects at this point, so I am going to default to copying for now. I would be happy to document/help w/ any top-level coordination to make it easier for any future projects that fall under Lucene (I'm holding my breath for the Pascal version of Lucene ) or to come up w/ a standard template for docs.

As always, the changes can be seen at http://people.apache.org/~gsingers/site/ (you may need to refresh or clear your cache to see the changes)

[Grant Ingersoll]

OK, this has been committed and people.apache.org has been updated (but give it 30-60 minutes to update). I will leave this issue open for a few days so people can post any problems w/ the new site w/o creating a new issue.

I deprecated ant docs in the build.xml (the target still exists, but it now does nothing, so if anyone has automated dependencies on this, they will want to update them). I removed <lucene>/site in favor of keeping the docs directory b/c I didn't know how people.apache.org would slurp up the website from a different directory and I didn't want to confuse people updating the website. The instructions at http://wiki.apache.org/jakarta-lucene/HowToUpdateTheWebsite have been modified accordingly.

We now have a favicon (yipee) that is checked in under the site src (<lucene>/src/site/src/documentation/content/xdocs/images) which is just the L part of the Lucene image file.

I have not hooked in code coverage (Issue 721) or nightly builds (Issue 708) yet but hope to get to that soon. I have not reverted the api docs to the last release, but will also try to get to that soon, as well.

As always, let me know of any issues. Future changes should be in the form of patches.

Thanks,
Grant

[Daniel Naber]

The link to the image (asf-logo.gif) in the upper left corner is broken (mhh, same problem at Nutch site).

[Grant Ingersoll]

Do you mean the feather logo and how it points to lucene.apache.org instead of apache.org?

This is a placeholder for now, as we need a separate logo for Lucene Java (since the green Lucene machine logo is both the logo for the top level project and for Lucene Java.) A graphic designer friend of mine has volunteered to produce a couple of variations using the current logo and the newly open sourced Duke logo.

[Hoss Man]

I believe the old version of the site had the feather there linking up to the top level Lucene website ... might want to put it back as a placeholder untill we get something better.

[Doug Cutting]

Lucene Java, Hadoop & Nutch all pointed to the image:

http://lucene.apache.org/java/docs/images/lucene_green_150.gif

which, after this site update, no longer exists.

I've fixed the Hadoop site to have its own copy of this image, as all of these should, so that they're standalone websites. We should probably do the same for Nutch.

[Sami Siren]

> We should probably do the same for Nutch.
I'll do that

[Marvin Humphrey]

One thing you might want to fix is the breadcrumb trail. The javascript that generates it automatically inserts an item for each directory in the URL. It's counter-intuitive, but in order to coerce the script into generating a link to lucene.apache.org/java/, you need to leave off the "java".

Here's how I have things set up for the Lucy breadcrumb trail in skinconf.xml:

<trail>
<link1 name="apache" href="http://www.apache.org/"/>
<link2 name="lucene" href="http://lucene.apache.org/"/>
<link3 name="" href=""/>
</trail>

"apache" and "lucene" are lowercased so that they will be consistent with the auto-extracted directory names.

Compare that third link with what currently exists in the Lucene Java skinconf.xml:

<trail>
<link1 name="Apache" href="http://www.apache.org/"/>
<link2 name="Lucene" href="http://lucene.apache.org/"/>
<link3 name="Java" href="http://lucene.apache.org/java/"/>
</trail>

Nutch, Hadoop, and Solr could all stand to make this change as well.

[Grant Ingersoll]

Thanks, I was wondering how to do that!

--------------------------
Grant Ingersoll
Center for Natural Language Processing
http://www.cnlp.org

Read the Lucene Java FAQ at http://wiki.apache.org/jakarta-lucene/
LuceneFAQ

[Grant Ingersoll]

New site is up and stable. The logo issue can be deferred to a new issue and handled separately. For now, the feather and the green Lucene logo are fine, I think.

[George Aroush]

Hi,

What will it take to fix the page at http://lucene.apache.org/ so that Lucene.Net is also on tab'ed-link? On the 22nd of Nov Otis pointed this out but I still don't see a mention of Lucene.Net.

Since Lucene4c is a "dead" project now, replacing it with Lucene.Net is an appropriate thing to do (Lucene.Net can use some exposure.) The link to Lucene.Net is: http://incubator.apache.org/lucene.net/

Also, as a note, the project name is "Lucene.Net" and not "Lucene.NET".

Thanks!

– George

[Grant Ingersoll]

Hi George,

This is a top level issue. You should be properly linked under the Lucene Java Related Projects section.

I would supply a patch based on http://svn.apache.org/viewvc/lucene/site and then somehow get the attention of one of the TLP committers (PMC members????, Doug?, Yonik?).

Good luck,
Grant

[George Aroush]

Thanks for the quick response Grant!

Unfortunately, I am not familiar with "forrest" which is how I believe the patch must be generated. If I supply the required text changes, can someone take care of making the changes? If not, can someone point me to where I can learn about "forrest"?

I believe Doug does have commit privilege.

Regards,

– George

[Doug Cutting]

PMC members maintain the top-level site. Please provide a patch. Thanks.

[George Aroush]

Hi Dough,

Attached is a patch to add Lucene.Net to TLP of Lucene site.

Thanks.

– George Aroush

[Erik Hatcher]

Applied, thanks George!