[infinispan-dev] Documentation code snippets

Alan Field afield at redhat.com
Fri May 5 11:30:01 EDT 2017


As confusing as this is, I agree with Tristan! :-)

----- Original Message -----
> From: "Tristan Tarrant" <ttarrant at redhat.com>
> To: "infinispan -Dev List" <infinispan-dev at lists.jboss.org>, "Jiri Holusa" <jholusa at redhat.com>
> Sent: Friday, May 5, 2017 11:12:31 AM
> Subject: Re: [infinispan-dev] Documentation code snippets
> 
> +1 for #2 from me too
> 
> Tristan
> 
> On 5/5/17 4:43 PM, Jiri Holusa wrote:
> > Hi Sebastian,
> > 
> > yes, you're right. I think the best way would be to go with option 2 making
> > it comprehensive, clean and transparent. I will issue another preview PR
> > soon that would contain some part from Hot Rod Client, ISPN Serven and
> > Embedded mode snippets making it as an example, what it would look like in
> > the end.
> > 
> > If anybody else has other opinions, please jump in, thanks.
> > Jiri
> > 
> > 
> > ----- Original Message -----
> >> From: "Sebastian Laskawiec" <slaskawi at redhat.com>
> >> To: "infinispan -Dev List" <infinispan-dev at lists.jboss.org>
> >> Sent: Friday, May 5, 2017 3:48:43 PM
> >> Subject: Re: [infinispan-dev] Documentation code snippets
> >>
> >> Hey Jiri,
> >>
> >> Very good investigation. I was all for option #2 (use existing testsuite)
> >> but
> >> now I'm leaning towards option #1 (separate testsuite).
> >>
> >> I believe there are 3 main parts to be tested and synced with
> >> documentation -
> >> Hot Rod Client, Infinispan Server and Embedded Mode. The first two can be
> >> tested together I think. To some extend this is already implemented in
> >> ExampleConfigsIT [1]. The Embedded Mode is much harder to test in my
> >> opinion, since the tests are spread all around the repo. I guess this will
> >> be the main challenge of this task.
> >>
> >> Thanks,
> >> Sebastian
> >>
> >> [1]
> >> https://github.com/infinispan/infinispan/blob/master/server/integration/testsuite/src/test/java/org/infinispan/server/test/configs/ExampleConfigsIT.java
> >>
> >> On Wed, May 3, 2017 at 3:20 PM Jiri Holusa < jholusa at redhat.com > wrote:
> >>
> >>
> >> Moving this to infinispan-dev.
> >>
> >> I've just issued a PR [1], where I setup the code snippets generation. It
> >> was
> >> actually pretty easy. I started implementing it for the configuration part
> >> of the documentation and I came across following findings/issues.
> >>
> >> There were more votes for option 2 (see the previous mail for detail, in
> >> summary using existing testsuite), hence I started with that. Pretty
> >> shortly
> >> I see following issues:
> >> * XML configuration - since we want to have the <infinispan> element there
> >> in
> >> the configuration, I have to do one XML file per one configuration code
> >> snippet -> the number of files will grow and will mess up the "normal"
> >> testsuite
> >> * IMHO biggest problem - our testsuite is usually not written in
> >> "documentation simplicity". For example, in testsuite we barely (= never)
> >> do
> >> "EmbeddedCacheManager cacheManager = new DefaultCacheManager("...");", we
> >> obtain the cache manager by some helper method. While this is great for
> >> testing, you don't want to have this in documentation as it should be
> >> simple
> >> and straightforward. Another example would be [2]. Look at the
> >> programmatic
> >> configuration snippets. In the testsuite, we usually don't have that
> >> trivial
> >> setup, not so comprehensively written somewhere.
> >> * When you want to introduce a new code snippet, how can you be sure that
> >> the
> >> snippet is not somewhere in the testsuite already, but written a bit
> >> differently? I encountered this right from the beginning, search the test
> >> classes and looking for "good enough" code snippet that I could use.
> >>
> >> Together it seems to me that it will mess up the testsuite quite a bit,
> >> make
> >> the maintenance of documentation harder and will significantly prolong the
> >> time needed for writing new documentation. What do you think? How about we
> >> went the same way as Hibernate (option 1 in first email) - creating
> >> separate
> >> documentation testsuite that is as simple as possible, descriptive and
> >> straightforward.
> >>
> >> I don't really care, which option we choose, I will implement it either
> >> way,
> >> but I wanted to show that there are some pitfalls of the option 2 as well
> >> :(
> >>
> >> Cheers,
> >> Jiri
> >>
> >> [1] https://github.com/infinispan/infinispan/pull/5115
> >> [2]
> >> http://infinispan.org/docs/stable/user_guide/user_guide.html#configuring_caches_programmatically
> >>
> >>
> >>
> >> ----- Forwarded Message -----
> >>> From: "Jiri Holusa" < jholusa at redhat.com >
> >>> To: "infinispan-internal" < infinispan-internal at redhat.com >
> >>> Sent: Friday, April 7, 2017 6:33:53 PM
> >>> Subject: [infinispan-internal] Documentation code snippets
> >>>
> >>> Hi everybody,
> >>>
> >>> during the documentation review for JDG 7.1 GA, I came across this little
> >>> thing.
> >>>
> >>> Having a good documentation is IMHO crucial for people to like our
> >>> technology
> >>> and the key point is having code snippets in the documentation up to date
> >>> and working. During review of my parts, I found out many and many
> >>> outdated
> >>> code snippets, either non-compilable or using deprecated methods. I would
> >>> like to eliminate this issue in the future, so it would make our
> >>> documentation better and also remove burden when doing documentation
> >>> review.
> >>>
> >>> I did some research and I found out that Hibernate team (thanks Radim,
> >>> Sanne
> >>> for the information) does a very cool thing and that is that the code
> >>> snippets are taken right from testsuite. This way they know that the code
> >>> snippet can always compile and also make sure that it's working properly.
> >>> I
> >>> would definitely love to see the same in Infinispan.
> >>>
> >>> It works extremely simply that you mark by comment in the test the part,
> >>> you
> >>> want to include in the documentation, see an example here for the
> >>> AsciiDoc
> >>> part [1] and here for the test part [2]. There are two ways of how to
> >>> organize that:
> >>> 1) create a separate "documentation testsuite", with as simple as
> >>> possible
> >>> test classes - Hibernate team does it this way. Pros: documentation is
> >>> easily separated. Cons: possible duplication.
> >>> 2) use existing testsuite, marking the parts in the existing testsuite.
> >>> Pros:
> >>> no duplication. Cons: documentation snippets are spread all across the
> >>> testsuite.
> >>>
> >>> I would definitely volunteer to make this happen in Infinispan
> >>> documentation.
> >>>
> >>> What do you guys think about it?
> >>>
> >>> Cheers,
> >>> Jiri
> >>>
> >>> [1]
> >>> https://raw.githubusercontent.com/hibernate/hibernate-validator/master/documentation/src/main/asciidoc/ch03.asciidoc
> >>> [2]
> >>> https://github.com/hibernate/hibernate-orm/blob/master/documentation/src/test/java/org/hibernate/userguide/caching/FirstLevelCacheTest.java
> >>>
> >>>
> >> _______________________________________________
> >> infinispan-dev mailing list
> >> infinispan-dev at lists.jboss.org
> >> https://lists.jboss.org/mailman/listinfo/infinispan-dev
> >> --
> >>
> >>
> >> SEBASTIAN ŁASKAWIEC
> >>
> >> INFINISPAN DEVELOPER
> >>
> >> Red Hat EMEA
> >>
> >> _______________________________________________
> >> infinispan-dev mailing list
> >> infinispan-dev at lists.jboss.org
> >> https://lists.jboss.org/mailman/listinfo/infinispan-dev
> > 
> > _______________________________________________
> > infinispan-dev mailing list
> > infinispan-dev at lists.jboss.org
> > https://lists.jboss.org/mailman/listinfo/infinispan-dev
> > 
> 
> --
> Tristan Tarrant
> Infinispan Lead
> JBoss, a division of Red Hat
> _______________________________________________
> infinispan-dev mailing list
> infinispan-dev at lists.jboss.org
> https://lists.jboss.org/mailman/listinfo/infinispan-dev



More information about the infinispan-dev mailing list