As confusing as this is, I agree with Tristan! :-) ----- Original Message ----- > From: "Tristan Tarrant" <ttarr...@redhat.com> > To: "infinispan -Dev List" <infinispan-dev@lists.jboss.org>, "Jiri Holusa" > <jhol...@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" <slask...@redhat.com> > >> To: "infinispan -Dev List" <infinispan-dev@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 < jhol...@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" < jhol...@redhat.com > > >>> To: "infinispan-internal" < infinispan-inter...@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@lists.jboss.org > >> https://lists.jboss.org/mailman/listinfo/infinispan-dev > >> -- > >> > >> > >> SEBASTIAN ĆASKAWIEC > >> > >> INFINISPAN DEVELOPER > >> > >> Red Hat EMEA > >> > >> _______________________________________________ > >> infinispan-dev mailing list > >> infinispan-dev@lists.jboss.org > >> https://lists.jboss.org/mailman/listinfo/infinispan-dev > > > > _______________________________________________ > > infinispan-dev mailing list > > infinispan-dev@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@lists.jboss.org > https://lists.jboss.org/mailman/listinfo/infinispan-dev
_______________________________________________ infinispan-dev mailing list infinispan-dev@lists.jboss.org https://lists.jboss.org/mailman/listinfo/infinispan-dev