flink-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Robert Metzger <rmetz...@apache.org>
Subject Re: Handling Integration of Documentation
Date Sun, 21 Sep 2014 15:21:32 GMT
No. I had the same issue.
The generated Java code looked ok (for generated code at least) and I could
not really understand why the Java compiler was complaining there.
Maybe you should open an issue (https://github.com/typesafehub/genjavadoc)
there.

On Sat, Sep 20, 2014 at 11:52 AM, Aljoscha Krettek <aljoscha@apache.org>
wrote:

> @Robert: Did you get genjavadoc to run? The problem I have right now
> is that the Java compiler complains because it cannot compile those
> fake java files generated by genjavadoc.
>
> On Fri, Sep 19, 2014 at 6:53 PM, Aljoscha Krettek <aljoscha@apache.org>
> wrote:
> > I updated my branch with some changes. Let me know what you think.
> >
> > On Fri, Sep 19, 2014 at 5:58 PM, Robert Metzger <rmetzger@apache.org>
> wrote:
> >> Mh. I'm actually preferring the old navigation style.
> >> The new navigation requires users to have JavaScript enabled (I know a
> lot
> >> of people who use NoScript).
> >> What I also liked about the old layout is that you can see very easily
> >> which pages are there.
> >>
> >> On Fri, Sep 19, 2014 at 5:37 PM, Kostas Tzoumas <ktzoumas@apache.org>
> wrote:
> >>
> >>> I guess the added value are the examples, which are nice to have for
> >>> someone that is learning.
> >>>
> >>> On Fri, Sep 19, 2014 at 5:15 PM, Aljoscha Krettek <aljoscha@apache.org
> >
> >>> wrote:
> >>>
> >>> > About the "Java API Transformations" Page. Why do we have it? The
> >>> > operations are described in the Javadoc for DataSet and Grouping.
> >>> > Having it duplicated here just means that we always have to keep it
> in
> >>> > sync. We could just have a link to the Javadoc in the Programming
> >>> > Guide in addition to the operations overview.
> >>> >
> >>> > What do you think?
> >>> >
> >>> > On Fri, Sep 19, 2014 at 3:48 PM, Kostas Tzoumas <ktzoumas@apache.org
> >
> >>> > wrote:
> >>> > > I like the new look as well. You could call it "Contents"
> >>> > >
> >>> > > Kostas
> >>> > >
> >>> > > On Fri, Sep 19, 2014 at 3:40 PM, Aljoscha Krettek <
> aljoscha@apache.org
> >>> >
> >>> > > wrote:
> >>> > >
> >>> > >> Yes, I know, their documentation structure is quite good and
I'm
> >>> > >> obviously inspired by it. :D Does anyone think this could
become a
> >>> > >> problem?
> >>> > >>
> >>> > >> The problem with "Overview" is that it is not clear whether
it's
> an
> >>> > >> overview of the documentation or Apache Flink in general.
But ok,
> >>> > >> let's go with Overview if no-one objects.
> >>> > >>
> >>> > >> I mention the Programming Guide in the first Paragraph but
If you
> come
> >>> > >> up with something better feel free to add it.
> >>> > >>
> >>> > >> I think doing PRs agains my repo should be easiest.
> >>> > >>
> >>> > >> @robert: I'm now also generating the javadoc via jekyll, it's
in
> >>> > >> _plugins/copy_api_dirs.rb
> >>> > >>
> >>> > >> On Fri, Sep 19, 2014 at 3:27 PM, Ufuk Celebi <uce@apache.org>
> wrote:
> >>> > >> > I like it very much, but a) there are some typos and
minor
> issues,
> >>> > and b)
> >>> > >> > it looks very much like [1] (I'm pointing this out without
any
> >>> > >> judgement).
> >>> > >> >
> >>> > >> > Regaring a) Should we post issues here or do a PR against
your
> repo?
> >>> > >> >
> >>> > >> > - I don't like the top link "Doc"... let's just called
it what
> it
> >>> is:
> >>> > >> > "Overview".
> >>> > >> > - And maybe let's put more attention on the link "Flink
> Programming
> >>> > >> Guide"
> >>> > >> > under "Programming Guides" somehow, because this is the
"main"
> >>> > >> programming
> >>> > >> > guide.
> >>> > >> >
> >>> > >> > [1] https://spark.apache.org/docs/latest/
> >>> > >> >
> >>> > >> > On Fri, Sep 19, 2014 at 3:12 PM, Aljoscha Krettek <
> >>> > aljoscha@apache.org>
> >>> > >> > wrote:
> >>> > >> >
> >>> > >> >> I updated the Documentation, now I need some eyeballs
to look
> this
> >>> > >> >> thing over so could you please have a look and tell
me what you
> >>> > think.
> >>> > >> >> :D
> >>> > >> >>
> >>> > >> >> I added and overview page, the programming guide
and the
> examples
> >>> are
> >>> > >> >> now unified. I also did some little touchups here
and there.
> >>> > >> >>
> >>> > >> >> To build it just checkout my scala-rework branch
and run the
> docs
> >>> > build
> >>> > >> >> script:
> >>> > >> >> https://github.com/aljoscha/incubator-flink/tree/scala-rework
> >>> > >> >>
> >>> > >> >> cd docs
> >>> > >> >> ./build_docs.sh -p
> >>> > >> >>
> >>> > >> >> On Fri, Sep 19, 2014 at 11:50 AM, Kostas Tzoumas
<
> >>> > ktzoumas@apache.org>
> >>> > >> >> wrote:
> >>> > >> >> > +1
> >>> > >> >> >
> >>> > >> >> > I think a standalone docs site with a different
nav bar will
> be
> >>> > more
> >>> > >> >> > usable.
> >>> > >> >> >
> >>> > >> >> > On Fri, Sep 19, 2014 at 11:03 AM, Aljoscha Krettek
<
> >>> > >> aljoscha@apache.org>
> >>> > >> >> > wrote:
> >>> > >> >> >
> >>> > >> >> >> > However, this would make the documentation
even more
> >>> > complicated.
> >>> > >> >> >>
> >>> > >> >> >> Exactly, that's what I'm trying to avoid.
> >>> > >> >> >>
> >>> > >> >> >> If nobody has anything against it I will
try to make the
> >>> > >> documentation
> >>> > >> >> >> self contained, move navigation to the top
bar, and
> generally
> >>> make
> >>> > >> >> >> things less cumbersome. :D
> >>> > >> >> >>
> >>> > >> >> >> On Fri, Sep 19, 2014 at 10:35 AM, Robert
Metzger <
> >>> > >> rmetzger@apache.org>
> >>> > >> >> >> wrote:
> >>> > >> >> >> > Hi Aljoscha,
> >>> > >> >> >> >
> >>> > >> >> >> > I think it should not be too difficult
to have different
> menu
> >>> > >> layouts
> >>> > >> >> for
> >>> > >> >> >> > the different versions of the website
documentation.
> However,
> >>> > this
> >>> > >> >> would
> >>> > >> >> >> > make the documentation even more complicated.
> >>> > >> >> >> >
> >>> > >> >> >> > I'm also unhappy with the current setup
of the
> documentation.
> >>> > The
> >>> > >> >> >> > maintenance is quite time-consuming,
so I'm happy if you
> come
> >>> up
> >>> > >> with
> >>> > >> >> a
> >>> > >> >> >> > simpler approach.
> >>> > >> >> >> >
> >>> > >> >> >> > I agree with having a self contained
documentation. This
> would
> >>> > also
> >>> > >> >> allow
> >>> > >> >> >> > us to make it part of the release votes
and ship it with
> the
> >>> > binary
> >>> > >> >> >> > releases.
> >>> > >> >> >> >
> >>> > >> >> >> >
> >>> > >> >> >> > I think it would be fine to just hardcode
a link to
> >>> > >> >> >> > flink.incubator.apache.org into the
standalone
> documentation.
> >>> > >> >> >> >
> >>> > >> >> >> >
> >>> > >> >> >> > Robert
> >>> > >> >> >> >
> >>> > >> >> >> >
> >>> > >> >> >> >
> >>> > >> >> >> > On Fri, Sep 19, 2014 at 9:45 AM, Aljoscha
Krettek <
> >>> > >> >> aljoscha@apache.org>
> >>> > >> >> >> > wrote:
> >>> > >> >> >> >
> >>> > >> >> >> >> Hi,
> >>> > >> >> >> >> I'm right now rewriting the documentation
to unify the
> Java
> >>> > >> API/Scala
> >>> > >> >> >> >> API parts with tabs to switch between
language (mentioned
> >>> that
> >>> > >> >> before,
> >>> > >> >> >> >> I know. :D).
> >>> > >> >> >> >>
> >>> > >> >> >> >> The problem is now that the doc
is very tightly
> integrated
> >>> into
> >>> > >> the
> >>> > >> >> >> >> website. For example, the sidebar
of links is part of the
> >>> > website.
> >>> > >> >> >> >> (The self contained doc also has
the sidebar of links,
> but if
> >>> > you
> >>> > >> >> look
> >>> > >> >> >> >> closely you will notice it's slightly
different.) It is
> the
> >>> > same
> >>> > >> for
> >>> > >> >> >> >> the 0.6 doc and the 0.7 doc, which
doesn't work well when
> >>> those
> >>> > >> two
> >>> > >> >> >> >> docs have different pages with
differing names.
> >>> > >> >> >> >>
> >>> > >> >> >> >> Would it not be easier to make
the documentation
> completely
> >>> > self
> >>> > >> >> >> >> contained (as it already is) and
copy the built files
> into
> >>> the
> >>> > >> >> >> >> website's doc folder. The website
would then just have
> links
> >>> to
> >>> > >> the
> >>> > >> >> >> >> documentation for the separate
versions.
> >>> > >> >> >> >>
> >>> > >> >> >> >> The problem would then be that
the documentation doesn't
> >>> share
> >>> > the
> >>> > >> >> >> >> same header as the website anymore.
I don't see this as a
> >>> > >> problem, we
> >>> > >> >> >> >> could even move the documentation
navigation into the
> header
> >>> > and
> >>> > >> out
> >>> > >> >> >> >> of the sidebar. Some people might
object though.
> >>> > >> >> >> >>
> >>> > >> >> >> >> What do you think? How should we
handle this?
> >>> > >> >> >> >>
> >>> > >> >> >> >> Cheers,
> >>> > >> >> >> >> Aljoscha
> >>> > >> >> >> >>
> >>> > >> >> >>
> >>> > >> >>
> >>> > >>
> >>> >
> >>>
>

Mime
  • Unnamed multipart/alternative (inline, None, 0 bytes)
View raw message