-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/
> Christopher L Tubbs II
> 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
> > links to javadoc from usermanual and visa versa). If we had a standard
> > 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