Very cool, this should be very useful to keep documentation up-to-date. Good job!
cheers Siemen On Tue, Jul 31, 2018 at 11:25 AM Quentin DUCASSE (CI_2020) < [email protected]> wrote: > Hello everyone! > > I am currently in an internship within the RMoD team and would like to > present my work. My internship subject was the following: “How to test > documents (books, slides) written in Pillar?”. Let me first introduce > Pillar then what I managed to implement and what is left to do. > > > > -*What is Pillar?* > > > > Pillar is a markup syntax and associated tools to write and generate > documentation, books, slide-based presentations or websites. Pillar syntax > is similar to Markdown’s one but its emphasis is stressed on publishing to > different formats/languages (Markdown, html, LateX, pdf). > > > > -*What does it mean to ‘test a book’?* > > > -- *Display code within the book* > > Pillar syntax allows you to write codeblocks, showing a part of code. The > inside of a codeblock allows one to display any part of code you might > want to. For example: > > [[[ > > YourClass >> yourMethod > > ^ ‘bla’ > > ]]] > > This codeblock presents a method definition, the other two possible > codeblocks are the following: > > > Class definition > > [[[ > > Object subclass: #YourClass > > instanceVariableNames: '' > > classVariableNames: '' > > package: YourPackage' > > ]]] > > > Example > > [[[ > > 1+1 > > >>> 2 > > ]]] > > > > -- *How to test it?* > > The use of ‘>>>’ and parameters in the codeblock will help us to test the > code within it. The BookTester will turn examples into tests. > > > > Testing examples: > > [[[testcase=true > > 3+4 becomes self assert: (3+4) equals: 7 > > >>>7 > > ]]] > > > Testing methodDefinitions and classDefinitions: > > > > Testing method or class definitions resumes is the same as testing if the > compilation of the method does not raise any error. It can help make sure > your book is up to date with the latest Pharo version. Those tests are done > the same way as testing an example: stating methodDefinition=true or > classDefinition=true as code block parameters will make them elible for > tests. Now, we are adding more features to code block or Pillar to help > book writers. > > > > -*Additional Features* > > In Pillar, several annotations can be used for different purposes like > including columns/tables/citations/figures/links… > > > > -- * Loading code:* loader > > ${loader:account=QDucasse|project=TestBook|tag=Chapter1}$ > > allows you to load the github project as it was in the commit tagged > Chapter1. This will help you test every chapter of your code with its > current progression and also allow you to test the objects you are defining > in your book. > > > - *Executing Tests:* run > > ${run:testClass=YourClassTest}$ runs the test defined in the class > testClass. And of course this testClass can be > > > Other annotations have been added to help you write your book: > > > - * Display a class definition:* showClass: > > ${showClass:className=YourClass}$ displays a codeblock with the class > definition within it > > This helps you quickly include a class definition you want to display in > your book. Combined with the loader it means that the code can be the > source of your book. > > > > - * Display a method definition:* showMethod: > > ${showMethod:className=YourClass|methodName=yourMethod}$ will display a > codeblock with the method definition within it > > This helps you quickly include a method definition you want to display in > your book. > > > > - * Screenshot:* > > > ${showMethod:packageName=yourPackage|className=YourClass|methodName=yourMethod|caption|width|label}$ > > saves a screenshot of a Calypso browser open at the selected package, > class and method and includes it in both your book (using the designated > Pillar figure reference) and the figures subfolder in the pillar book > folder (saved as PNG). > > > -*Future objectives* > > > > One of the future improvements would be to make everyone able to write > examples and test them in the comments of method definitions. It is already > partially possible “3+4 >>> 7” will be highlighted differently and if > printed will display “7->7”. However, an automation or UI improvement would > be nice. > > > > I hope this gave you the will to write something you had in mind. Are > there any books you want to try the tools on? Feel free to ask ! > > > > Quentin Ducasse > >
