+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
