{"id":165,"date":"2016-06-15T22:48:15","date_gmt":"2016-06-15T21:48:15","guid":{"rendered":"https:\/\/blogs.churlaud.com\/somefoobar\/?p=165"},"modified":"2016-06-15T23:12:27","modified_gmt":"2016-06-15T22:12:27","slug":"writing-up-to-date-tutorials-with-doxygen","status":"publish","type":"post","link":"https:\/\/blogs.churlaud.com\/somefoobar\/2016\/06\/15\/writing-up-to-date-tutorials-with-doxygen\/","title":{"rendered":"Writing up-to-date tutorials with Doxygen"},"content":{"rendered":"<p>The other day we were discussing on <kbd>#plasma<\/kbd> about KApiDox and what the Plasma team needed to write awesome documentation. Sebas and Martin were specially complaining about the fact that keeping a tutorial up-to-date was difficult because it is only text which will never be compiled for real by the writer, or not as presented.<\/p>\n<h3>The solution<\/h3>\n<p>I&#8217;d like to share the solution that Doxygen propose (adapted from the Doxygen documentation <a href=\"http:\/\/www.stack.nl\/~dimitri\/doxygen\/manual\/commands.html#cmdsnippet\">[1]<\/a>):<\/p>\n<p>The command is <\/p>\n<pre>\r\n\\snippet &lt;file-name&gt; ( block_id )\r\n<\/pre>\n<p>Contrary to <kbd>\\include<\/kbd> that includes a complete file as source code, this only quotes a fragment of a file. To refer to the same file you are documenting, use <kbd>this<\/kbd> as the <kbd>&lt;file-name&gt;<\/kbd><\/p>\n<p>For example, the putting the following command in the documentation, references a snippet in file <kbd>example.cpp<\/kbd> residing in a subdirectory which should be pointed to by <kbd>EXAMPLE_PATH<\/kbd>.<\/p>\n<pre>\r\n \/**\r\n  * ....\r\n  * A resource can easily be added with:\r\n  * \\snippet snippets\/example.cpp Adding a resource\r\n  * ...\r\n<\/pre>\n<p>A unique identifier refers to the snippet defined as followed<\/p>\n<pre>\r\n    QImage image(64, 64, QImage::Format_RGB32);\r\n    image.fill(qRgb(255, 160, 128));\r\n\/\/! [Adding a resource]\r\n    document->addResource(QTextDocument::ImageResource,\r\n        QUrl(\"mydata:\/\/image.png\"), QVariant(image));\r\n\/\/! [Adding a resource]\r\n    ...\r\n<\/pre>\n<p>The output of the snippet command is:<\/p>\n<pre>\r\ndocument->addResource(QTextDocument::ImageResource,\r\n    QUrl(\"mydata:\/\/image.png\"), QVariant(image));\r\n<\/pre>\n<h3>What follows<\/h3>\n<p>I updated the wiki <a href=\"https:\/\/community.kde.org\/Guidelines_and_HOWTOs\/API_Documentation#Code_Examples_in_APIDOX\">[2]<\/a>, and now you can continue writing awesome documentation about how to use your libraries. <\/p>\n<p>You know what? The more it goes, the more I think that Techbase is slowly becoming useless&#8230; But Schhhhtttttt&#8230; this is a secret. \ud83d\ude00<\/p>\n<p>Cheers and have fun !<\/p>\n<h3>Sources<\/h3>\n<p>[1] <a href=\"http:\/\/www.stack.nl\/~dimitri\/doxygen\/manual\/commands.html#cmdsnippet\">http:\/\/www.stack.nl\/~dimitri\/doxygen\/manual\/commands.html#cmdsnippet<\/a><br \/>\n[2] <a href=\"https:\/\/community.kde.org\/Guidelines_and_HOWTOs\/API_Documentation#Code_Examples_in_APIDOX\">https:\/\/community.kde.org\/Guidelines_and_HOWTOs\/API_Documentation#Code_Examples_in_APIDOX<\/a><\/p>\n","protected":false},"excerpt":{"rendered":"<p>The other day we were discussing on #plasma about KApiDox and what the Plasma team needed to write awesome documentation. Sebas and Martin were specially complaining about the fact that keeping a tutorial up-to-date was difficult because it is only text which will never be compiled for real by the writer, or not as presented.<\/p>\n<p><a class=\"button\" href=\"https:\/\/blogs.churlaud.com\/somefoobar\/2016\/06\/15\/writing-up-to-date-tutorials-with-doxygen\/\" title=\"More\">  Read More \u2192<\/a><\/p>\n","protected":false},"author":8,"featured_media":0,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"iawp_total_views":6,"footnotes":""},"categories":[11],"tags":[18,21,20,13,19],"class_list":["post-165","post","type-post","status-publish","format-standard","hentry","category-kde","tag-documentation","tag-doxygen","tag-kapidox","tag-kde","tag-techbase"],"yoast_head":"<!-- This site is optimized with the Yoast SEO plugin v27.2 - https:\/\/yoast.com\/product\/yoast-seo-wordpress\/ -->\n<title>Writing up-to-date tutorials with Doxygen - Just some FooBar<\/title>\n<meta name=\"robots\" content=\"index, follow, max-snippet:-1, max-image-preview:large, max-video-preview:-1\" \/>\n<link rel=\"canonical\" href=\"https:\/\/blogs.churlaud.com\/somefoobar\/2016\/06\/15\/writing-up-to-date-tutorials-with-doxygen\/\" \/>\n<meta property=\"og:locale\" content=\"en_US\" \/>\n<meta property=\"og:type\" content=\"article\" \/>\n<meta property=\"og:title\" content=\"Writing up-to-date tutorials with Doxygen - Just some FooBar\" \/>\n<meta property=\"og:description\" content=\"The other day we were discussing on #plasma about KApiDox and what the Plasma team needed to write awesome documentation. Sebas and Martin were specially complaining about the fact that keeping a tutorial up-to-date was difficult because it is only text which will never be compiled for real by the writer, or not as presented. Read More \u2192\" \/>\n<meta property=\"og:url\" content=\"https:\/\/blogs.churlaud.com\/somefoobar\/2016\/06\/15\/writing-up-to-date-tutorials-with-doxygen\/\" \/>\n<meta property=\"og:site_name\" content=\"Just some FooBar\" \/>\n<meta property=\"article:published_time\" content=\"2016-06-15T21:48:15+00:00\" \/>\n<meta property=\"article:modified_time\" content=\"2016-06-15T22:12:27+00:00\" \/>\n<meta name=\"author\" content=\"Olivier\" \/>\n<meta name=\"twitter:card\" content=\"summary_large_image\" \/>\n<meta name=\"twitter:label1\" content=\"Written by\" \/>\n\t<meta name=\"twitter:data1\" content=\"Olivier\" \/>\n\t<meta name=\"twitter:label2\" content=\"Est. reading time\" \/>\n\t<meta name=\"twitter:data2\" content=\"1 minute\" \/>\n<script type=\"application\/ld+json\" class=\"yoast-schema-graph\">{\"@context\":\"https:\/\/schema.org\",\"@graph\":[{\"@type\":\"Article\",\"@id\":\"https:\/\/blogs.churlaud.com\/somefoobar\/2016\/06\/15\/writing-up-to-date-tutorials-with-doxygen\/#article\",\"isPartOf\":{\"@id\":\"https:\/\/blogs.churlaud.com\/somefoobar\/2016\/06\/15\/writing-up-to-date-tutorials-with-doxygen\/\"},\"author\":{\"name\":\"Olivier\",\"@id\":\"https:\/\/blogs.churlaud.com\/somefoobar\/#\/schema\/person\/ee53ba4920ebe33c29228fd0e42e42f6\"},\"headline\":\"Writing up-to-date tutorials with Doxygen\",\"datePublished\":\"2016-06-15T21:48:15+00:00\",\"dateModified\":\"2016-06-15T22:12:27+00:00\",\"mainEntityOfPage\":{\"@id\":\"https:\/\/blogs.churlaud.com\/somefoobar\/2016\/06\/15\/writing-up-to-date-tutorials-with-doxygen\/\"},\"wordCount\":233,\"commentCount\":1,\"keywords\":[\"documentation\",\"doxygen\",\"KApidox\",\"kde\",\"techbase\"],\"articleSection\":[\"Kde\"],\"inLanguage\":\"en-US\",\"potentialAction\":[{\"@type\":\"CommentAction\",\"name\":\"Comment\",\"target\":[\"https:\/\/blogs.churlaud.com\/somefoobar\/2016\/06\/15\/writing-up-to-date-tutorials-with-doxygen\/#respond\"]}]},{\"@type\":\"WebPage\",\"@id\":\"https:\/\/blogs.churlaud.com\/somefoobar\/2016\/06\/15\/writing-up-to-date-tutorials-with-doxygen\/\",\"url\":\"https:\/\/blogs.churlaud.com\/somefoobar\/2016\/06\/15\/writing-up-to-date-tutorials-with-doxygen\/\",\"name\":\"Writing up-to-date tutorials with Doxygen - Just some FooBar\",\"isPartOf\":{\"@id\":\"https:\/\/blogs.churlaud.com\/somefoobar\/#website\"},\"datePublished\":\"2016-06-15T21:48:15+00:00\",\"dateModified\":\"2016-06-15T22:12:27+00:00\",\"author\":{\"@id\":\"https:\/\/blogs.churlaud.com\/somefoobar\/#\/schema\/person\/ee53ba4920ebe33c29228fd0e42e42f6\"},\"breadcrumb\":{\"@id\":\"https:\/\/blogs.churlaud.com\/somefoobar\/2016\/06\/15\/writing-up-to-date-tutorials-with-doxygen\/#breadcrumb\"},\"inLanguage\":\"en-US\",\"potentialAction\":[{\"@type\":\"ReadAction\",\"target\":[\"https:\/\/blogs.churlaud.com\/somefoobar\/2016\/06\/15\/writing-up-to-date-tutorials-with-doxygen\/\"]}]},{\"@type\":\"BreadcrumbList\",\"@id\":\"https:\/\/blogs.churlaud.com\/somefoobar\/2016\/06\/15\/writing-up-to-date-tutorials-with-doxygen\/#breadcrumb\",\"itemListElement\":[{\"@type\":\"ListItem\",\"position\":1,\"name\":\"Accueil\",\"item\":\"https:\/\/blogs.churlaud.com\/somefoobar\/\"},{\"@type\":\"ListItem\",\"position\":2,\"name\":\"Writing up-to-date tutorials with Doxygen\"}]},{\"@type\":\"WebSite\",\"@id\":\"https:\/\/blogs.churlaud.com\/somefoobar\/#website\",\"url\":\"https:\/\/blogs.churlaud.com\/somefoobar\/\",\"name\":\"Just some FooBar\",\"description\":\"Not much to say...\",\"potentialAction\":[{\"@type\":\"SearchAction\",\"target\":{\"@type\":\"EntryPoint\",\"urlTemplate\":\"https:\/\/blogs.churlaud.com\/somefoobar\/?s={search_term_string}\"},\"query-input\":{\"@type\":\"PropertyValueSpecification\",\"valueRequired\":true,\"valueName\":\"search_term_string\"}}],\"inLanguage\":\"en-US\"},{\"@type\":\"Person\",\"@id\":\"https:\/\/blogs.churlaud.com\/somefoobar\/#\/schema\/person\/ee53ba4920ebe33c29228fd0e42e42f6\",\"name\":\"Olivier\",\"image\":{\"@type\":\"ImageObject\",\"inLanguage\":\"en-US\",\"@id\":\"https:\/\/secure.gravatar.com\/avatar\/da8de930ce1a22e92ce36b824ee34d1230fb0294d77eebfaa645282ed474f688?s=96&d=mm&r=g\",\"url\":\"https:\/\/secure.gravatar.com\/avatar\/da8de930ce1a22e92ce36b824ee34d1230fb0294d77eebfaa645282ed474f688?s=96&d=mm&r=g\",\"contentUrl\":\"https:\/\/secure.gravatar.com\/avatar\/da8de930ce1a22e92ce36b824ee34d1230fb0294d77eebfaa645282ed474f688?s=96&d=mm&r=g\",\"caption\":\"Olivier\"},\"sameAs\":[\"http:\/\/olivier.churlaud.com\"],\"url\":\"https:\/\/blogs.churlaud.com\/somefoobar\/author\/olivier\/\"}]}<\/script>\n<!-- \/ Yoast SEO plugin. -->","yoast_head_json":{"title":"Writing up-to-date tutorials with Doxygen - Just some FooBar","robots":{"index":"index","follow":"follow","max-snippet":"max-snippet:-1","max-image-preview":"max-image-preview:large","max-video-preview":"max-video-preview:-1"},"canonical":"https:\/\/blogs.churlaud.com\/somefoobar\/2016\/06\/15\/writing-up-to-date-tutorials-with-doxygen\/","og_locale":"en_US","og_type":"article","og_title":"Writing up-to-date tutorials with Doxygen - Just some FooBar","og_description":"The other day we were discussing on #plasma about KApiDox and what the Plasma team needed to write awesome documentation. Sebas and Martin were specially complaining about the fact that keeping a tutorial up-to-date was difficult because it is only text which will never be compiled for real by the writer, or not as presented. Read More \u2192","og_url":"https:\/\/blogs.churlaud.com\/somefoobar\/2016\/06\/15\/writing-up-to-date-tutorials-with-doxygen\/","og_site_name":"Just some FooBar","article_published_time":"2016-06-15T21:48:15+00:00","article_modified_time":"2016-06-15T22:12:27+00:00","author":"Olivier","twitter_card":"summary_large_image","twitter_misc":{"Written by":"Olivier","Est. reading time":"1 minute"},"schema":{"@context":"https:\/\/schema.org","@graph":[{"@type":"Article","@id":"https:\/\/blogs.churlaud.com\/somefoobar\/2016\/06\/15\/writing-up-to-date-tutorials-with-doxygen\/#article","isPartOf":{"@id":"https:\/\/blogs.churlaud.com\/somefoobar\/2016\/06\/15\/writing-up-to-date-tutorials-with-doxygen\/"},"author":{"name":"Olivier","@id":"https:\/\/blogs.churlaud.com\/somefoobar\/#\/schema\/person\/ee53ba4920ebe33c29228fd0e42e42f6"},"headline":"Writing up-to-date tutorials with Doxygen","datePublished":"2016-06-15T21:48:15+00:00","dateModified":"2016-06-15T22:12:27+00:00","mainEntityOfPage":{"@id":"https:\/\/blogs.churlaud.com\/somefoobar\/2016\/06\/15\/writing-up-to-date-tutorials-with-doxygen\/"},"wordCount":233,"commentCount":1,"keywords":["documentation","doxygen","KApidox","kde","techbase"],"articleSection":["Kde"],"inLanguage":"en-US","potentialAction":[{"@type":"CommentAction","name":"Comment","target":["https:\/\/blogs.churlaud.com\/somefoobar\/2016\/06\/15\/writing-up-to-date-tutorials-with-doxygen\/#respond"]}]},{"@type":"WebPage","@id":"https:\/\/blogs.churlaud.com\/somefoobar\/2016\/06\/15\/writing-up-to-date-tutorials-with-doxygen\/","url":"https:\/\/blogs.churlaud.com\/somefoobar\/2016\/06\/15\/writing-up-to-date-tutorials-with-doxygen\/","name":"Writing up-to-date tutorials with Doxygen - Just some FooBar","isPartOf":{"@id":"https:\/\/blogs.churlaud.com\/somefoobar\/#website"},"datePublished":"2016-06-15T21:48:15+00:00","dateModified":"2016-06-15T22:12:27+00:00","author":{"@id":"https:\/\/blogs.churlaud.com\/somefoobar\/#\/schema\/person\/ee53ba4920ebe33c29228fd0e42e42f6"},"breadcrumb":{"@id":"https:\/\/blogs.churlaud.com\/somefoobar\/2016\/06\/15\/writing-up-to-date-tutorials-with-doxygen\/#breadcrumb"},"inLanguage":"en-US","potentialAction":[{"@type":"ReadAction","target":["https:\/\/blogs.churlaud.com\/somefoobar\/2016\/06\/15\/writing-up-to-date-tutorials-with-doxygen\/"]}]},{"@type":"BreadcrumbList","@id":"https:\/\/blogs.churlaud.com\/somefoobar\/2016\/06\/15\/writing-up-to-date-tutorials-with-doxygen\/#breadcrumb","itemListElement":[{"@type":"ListItem","position":1,"name":"Accueil","item":"https:\/\/blogs.churlaud.com\/somefoobar\/"},{"@type":"ListItem","position":2,"name":"Writing up-to-date tutorials with Doxygen"}]},{"@type":"WebSite","@id":"https:\/\/blogs.churlaud.com\/somefoobar\/#website","url":"https:\/\/blogs.churlaud.com\/somefoobar\/","name":"Just some FooBar","description":"Not much to say...","potentialAction":[{"@type":"SearchAction","target":{"@type":"EntryPoint","urlTemplate":"https:\/\/blogs.churlaud.com\/somefoobar\/?s={search_term_string}"},"query-input":{"@type":"PropertyValueSpecification","valueRequired":true,"valueName":"search_term_string"}}],"inLanguage":"en-US"},{"@type":"Person","@id":"https:\/\/blogs.churlaud.com\/somefoobar\/#\/schema\/person\/ee53ba4920ebe33c29228fd0e42e42f6","name":"Olivier","image":{"@type":"ImageObject","inLanguage":"en-US","@id":"https:\/\/secure.gravatar.com\/avatar\/da8de930ce1a22e92ce36b824ee34d1230fb0294d77eebfaa645282ed474f688?s=96&d=mm&r=g","url":"https:\/\/secure.gravatar.com\/avatar\/da8de930ce1a22e92ce36b824ee34d1230fb0294d77eebfaa645282ed474f688?s=96&d=mm&r=g","contentUrl":"https:\/\/secure.gravatar.com\/avatar\/da8de930ce1a22e92ce36b824ee34d1230fb0294d77eebfaa645282ed474f688?s=96&d=mm&r=g","caption":"Olivier"},"sameAs":["http:\/\/olivier.churlaud.com"],"url":"https:\/\/blogs.churlaud.com\/somefoobar\/author\/olivier\/"}]}},"_links":{"self":[{"href":"https:\/\/blogs.churlaud.com\/somefoobar\/wp-json\/wp\/v2\/posts\/165","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/blogs.churlaud.com\/somefoobar\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/blogs.churlaud.com\/somefoobar\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/blogs.churlaud.com\/somefoobar\/wp-json\/wp\/v2\/users\/8"}],"replies":[{"embeddable":true,"href":"https:\/\/blogs.churlaud.com\/somefoobar\/wp-json\/wp\/v2\/comments?post=165"}],"version-history":[{"count":6,"href":"https:\/\/blogs.churlaud.com\/somefoobar\/wp-json\/wp\/v2\/posts\/165\/revisions"}],"predecessor-version":[{"id":171,"href":"https:\/\/blogs.churlaud.com\/somefoobar\/wp-json\/wp\/v2\/posts\/165\/revisions\/171"}],"wp:attachment":[{"href":"https:\/\/blogs.churlaud.com\/somefoobar\/wp-json\/wp\/v2\/media?parent=165"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/blogs.churlaud.com\/somefoobar\/wp-json\/wp\/v2\/categories?post=165"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/blogs.churlaud.com\/somefoobar\/wp-json\/wp\/v2\/tags?post=165"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}