The annual KDE Randa Meeting, in itself already shock-ful of awesome, this year hosted the KDE Frameworks Cookbook sprint. Valorie, Cornelius and I already wrote a lot about it. Plenty of attention went into finding the place for the cookbook between the getting-started HOWTOs on KDE Techbase and the full-blown API documentation. Not surprisingly, there is a space and a good purpose for the book. Frameworks developers and maintainer have had to deal with the question of where to put introductions that segue newcomers into how to use the modules many times, and so far, the answer have been unsatisfactory. Newcomers only find the API documentation when they already know about a framework, and TechBase is a great resource for developers, but not necessarily a good introduction. What is missing is a good way to help and learn about what KDE Frameworks have to offer. So there is the purpose of the KDE Frameworks Cookbook – to help developers find and learn about the right tools for the problems they need to solve (and also, consumable on a e-book reader by the pool). For developers and maintainers, this means they need to know how to add sections to the book that cover this information about their frameworks. These tools and workflows will be explained in this post.
Im a way, the book will partly provide an alternative way to consume the content provided by KDE TechBase. Because of that, the HTML version of the book will integrate and cross-link with TechBase. The preferences of what kind of documentation should be in the book or on TechBase are not yet written in stone, and will probably develop over time. The beauty of Free Software is that it also does not matter much – the content is there and may be mixed and remixed as needed.
Two principles have been applied when setting up the tooling for the KDE Framworks Cookbook. The first is that content should stay in the individual frameworks repositories as much as possible. The second is that content taken from the frameworks, like code snippets, shall not be duplicated into the book, but rather referenced and extracted at build time.
Keeping content that is part of the book in the frameworks repositories makes it easier for developers and maintainers to contribute to it. A book can grow to ginormous proportions, and keeping track of where its text is related to a specific framework or piece of code will be difficult if the two are separated into different places. However, content that is not specific to individual frameworks may as well be placed in the book repository. Considering that contributions of code and prose are voluntary and compete for the available time of the people working on it, it is important to keep the workflow simple, straightforward and integrated with that of development. Frameworks authors add sections to the book by placing Markdown formatted texts in the framework’s repository. The repository for the book (
kde:kf5book) references the frameworks repositories that provide content as Git submodules, and defines the order in which the content is included using a CMake based build system. The target formats of the book, currently PDF, HTML and ePub, are generated using pandoc. Pandoc can also be used by the contributors to preview the text they have written and check it for correct formatting. The book repository already contains various sections pulled in from the frameworks repositories this ways. Interested contributors will probably find it easiest to follow the existing examples for the submodule setup and the build instructions in the
CMakeLists.txt file to add their content. The ThreadWeaver repository (
kde:threadweaver) contains Markdown files that are part of the cookbook in it’s
examples/ folder which can serve as a reference. See below for why the file names end in
Avoiding duplication by copy-pasting code into the book is achieved by using a special markup for code snippets and other examples and a separate tool to extract them. Especially example and unit test code that is shown in the book should always be part of the regular, CI tested build of the respective framework. This ensures that all code samples shown in the book actually compile and hopefully work for the reader. The
snippetextractor tool processes the input files that only contain references to the code samples and produces complete Markdown files that include the samples verbatim. The input file names end in
.in.md. The conversion of the input files is handled by the build system of the
kf5book repository, not in the individual frameworks repositories. It is however possible to add steps to produce the final Markdown files to the CMake build files of the repository. This will catch markup errors of snippets during the frameworks build, but does require the
snippetextractor tool to be installed.
Setting up continuous builds for the book target formats is currently being worked on. Producing the book will be integrated into KDE’s Jenkins CI, and up-to-date version of it will be available on KDE TechBase. Until then, curious readers can self-produce the book:
- Install pandoc and the necessary Latex packages to produce PDF output.
- Build and install
snippetextractorusing QMake and a recent (>5.2) Qt. Make sure it is in the path before running CMake in the later steps.
kde:kf5book, and initialize the Git submodules as described in the README file.
- In a build directory, run
cmake <source directory>and
maketo produce the book.