[infinispan-dev] Documentation code snippets

Fri May 5 09:48:43 EDT 2017

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 <https://www.redhat.com/>
<https://red.ht/sig>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://lists.jboss.org/pipermail/infinispan-dev/attachments/20170505/4f337b75/attachment-0001.html 