[infinispan-dev] Documentation code snippets

Tristan Tarrant ttarrant at redhat.com
Fri May 5 11:12:31 EDT 2017


+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


More information about the infinispan-dev mailing list