Home | About | Sematext search-lucene.com search-hadoop.com
 Search Hadoop and all its subprojects:

Switch to Threaded View
Accumulo, mail # dev - Docs with monitor


Copy link to this message
-
Re: Docs with monitor
Keith Turner 2013-06-04, 19:55
On Tue, Jun 4, 2013 at 3:36 PM, Christopher <[EMAIL PROTECTED]> wrote:

> That would be nice, but we should avoid relative paths in javadocs
> that link externally, because they also get packaged in the -javadoc
> jars, and should be independent.
>

We could use the structure you discussed for docs on the accumulo site to
put absolute links into the javadocs.   Would be nice to do this in such a
way that we could verify the docs w/ a link checker prior to release.
 Seems like this would require the ability to set the link prefix in one
place, and then generate docs w/ that prefix.  Not sure how to do this w/
javadoc.
>
> --
> Christopher L Tubbs II
> http://gravatar.com/ctubbsii
>
>
> On Tue, Jun 4, 2013 at 3:25 PM, Keith Turner <[EMAIL PROTECTED]> wrote:
> > Something I have wanted w/ Accumulo documention is have more linking
> (i.e.
> > links to javadoc from usermanual and visa versa).  If we had a standard
> dir
> > structure, then we could have relative links between components.
> >
> >
> > On Tue, Jun 4, 2013 at 2:05 PM, Christopher <[EMAIL PROTECTED]> wrote:
> >
> >> Documentation is spread out everywhere, and it's a bit difficult to
> >> keep it consistent and up-to-date.
> >>
> >> I think we should focus on keeping per-version documentation
> >> up-to-date on the Accumulo website and in the user manual/book instead
> >> of relying on the maintenance of random READMEs, docs/*.html on the
> >> monitor, etc.
> >>
> >> I opened one issue (ACCUMULO-1487) related to this, but I'm looking at
> >> the links in docs/*.html and it seems they are written with the
> >> assumption that they are being served from the monitor. I'm not sure
> >> how useful these are. Perhaps it'd be better if these were simply
> >> removed from the monitor, and replaced with a link to the website
> >> documentation (link configurable)?
> >>
> >> That said, it would probably benefit us to have documentation links such
> >> as:
> >>
> >> http://accumulo.apache.org/docs/1.5/ -> points to latest 1.5.x
> >> http://accumulo.apache.org/docs/1.5.1/
> >> http://accumulo.apache.org/docs/latest/ -> points to latest overall
> >> version (menu includes links to older versions)
> >> http://accumulo.apache.org/docs/ -> redirects to docs/latest
> >>
> >> So, this email is about two things, really:
> >>
> >> 1) Improve the website with consolidated per-version documentation.
> >> 2) Get rid of documentation packaged with the monitor.
> >>
> >> This doesn't address the consolidation of the various READMEs, but
> >> those should be addressed at some point also.
> >>
> >> I also opened ACCUMULO-1490, ACCUMULO-1491 to deal with this. And, as
> >> part of improvements for ACCUMULO-935, I already made a separate
> >> "docs" module that could probably benefit from some further polishing.
> >>
> >> Thoughts?
> >>
> >> --
> >> Christopher L Tubbs II
> >> http://gravatar.com/ctubbsii
> >>
>