@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 <[email protected]> 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 <[email protected]> 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 <[email protected]> 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 <[email protected]> >>> 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 <[email protected]> >>> > 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 <[email protected] >>> > >>> > > 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 <[email protected]> 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 < >>> > [email protected]> >>> > >> > 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 < >>> > [email protected]> >>> > >> >> 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 < >>> > >> [email protected]> >>> > >> >> > 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 < >>> > >> [email protected]> >>> > >> >> >> 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 < >>> > >> >> [email protected]> >>> > >> >> >> > 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 >>> > >> >> >> >> >>> > >> >> >> >>> > >> >> >>> > >> >>> > >>>
