doc: using an actual snippet from the getting started app source.

doc/generated/CMakeLists.txt

@@ -49,11 +49,6 @@ endif()
 configure_file(${CMAKE_CURRENT_SOURCE_DIR}/configure.h.cmake
                ${CMAKE_CURRENT_BINARY_DIR}/configure.h)
 
-add_executable(hello hello.cpp)
-target_link_libraries(hello
-    Magnum::Magnum
-    Magnum::Application)
-
 add_executable(shaders shaders.cpp)
 target_include_directories(shaders PRIVATE ${CMAKE_CURRENT_BINARY_DIR})
 target_link_libraries(shaders

doc/generated/README.md

@@ -12,21 +12,6 @@ Create build dir, point CMake to this directory and compile the executables:
     cmake ../doc/generated
     cmake --build .
 
-### "Getting started" image
-
-Displayed by the `hello` executable. Run the app and take screenshot using
-KSnapshot (including decorations, 880x707). Similarly for the gray version. The
-resulting files should be resized to half the size and without alpha channel
-using imagemagick:
-
-```bash
-mogrify -flatten -background '#ffffff' -resize 440 getting-started.png
-mogrify -flatten -background '#ffffff' -resize 440 getting-started-blue.png
-```
-
-The output printed by the application can be used to update the example output
-in `doc/getting-started.dox`.
-
 ### Shader images
 
 Generated by the `shaders` executable. Must be run in this directory, the

doc/generated/shaders.cpp

@@ -144,7 +144,7 @@ int ShaderVisualizer::exec() {
 namespace {
     const auto Projection = Matrix4::perspectiveProjection(35.0_degf, 1.0f, 0.001f, 100.0f);
     const auto Transformation = Matrix4::translation(Vector3::zAxis(-5.0f));
-    const auto BaseColor = Color3::fromHSV(216.0_degf, 0.85f, 1.0f);
+    const auto BaseColor = Color3::fromHsv(216.0_degf, 0.85f, 1.0f);
     const auto OutlineColor = Color3{0.95f};
 }
 
@@ -209,7 +209,7 @@ std::string ShaderVisualizer::vertexColor() {
     std::vector<Color3> colors;
     colors.reserve(sphere.positions(0).size());
     for(Vector3 position: sphere.positions(0))
-        colors.push_back(Color3::fromHSV(Math::lerp(240.0_degf, 420.0_degf, Math::max(1.0f - (position - target).length(), 0.0f)), 0.85f, 0.85f));
+        colors.push_back(Color3::fromHsv(Math::lerp(240.0_degf, 420.0_degf, Math::max(1.0f - (position - target).length(), 0.0f)), 0.85f, 0.85f));
 
     Buffer vertices, indices;
     vertices.setData(MeshTools::interleave(sphere.positions(0), colors), BufferUsage::StaticDraw);

doc/getting-started.dox

@@ -115,34 +115,7 @@ The `src/` directory contains the actual project. To keep things simple, the
 project consists of just a single `MyApplication.cpp` file with the most
 minimal code possible:
 
-@code{.cpp}
-#include <Magnum/DefaultFramebuffer.h>
-#include <Magnum/Platform/Sdl2Application.h>
-
-using namespace Magnum;
-
-class MyApplication: public Platform::Application {
-    public:
-        explicit MyApplication(const Arguments& arguments);
-
-    private:
-        void drawEvent() override;
-};
-
-MyApplication::MyApplication(const Arguments& arguments): Platform::Application{arguments} {
-    // TODO: Add your initialization code here
-}
-
-void MyApplication::drawEvent() {
-    defaultFramebuffer.clear(FramebufferClear::Color);
-
-    // TODO: Add your drawing code here
-
-    swapBuffers();
-}
-
-MAGNUM_APPLICATION_MAIN(MyApplication)
-@endcode
+@snippet getting-started.cpp 0
 
 The application essentially does nothing, just clears the screen framebuffer to
 default (dark gray) color and then does buffer swap to actually display it on
@@ -229,24 +202,12 @@ the concepts of graphics programming, we can change the clear color to
 something else and also print basic information about the GPU the engine is
 running on. First include the needed headers:
 
-@code{.cpp}
-#include <Magnum/Context.h>
-#include <Magnum/Renderer.h>
-#include <Magnum/Version.h>
-#include <Magnum/Math/Color.h>
-@endcode
+@snippet getting-started-blue.cpp 0
 
 And in the constructor (which is currently empty) change the clear color and
 print something to debug output:
 
-@code{.cpp}
-    using namespace Magnum::Math::Literals;
-
-    Renderer::setClearColor(0xa5c9ea_rgbf);
-
-    Debug() << "Hello! This application is running on" << Context::current().version()
-            << "using" << Context::current().rendererString();
-@endcode
+@snippet getting-started-blue.cpp 1
 
 After rebuilding and starting the application, the clear color changes to
 blueish one and something like this would be printed to the console:

doc/snippets/CMakeLists.txt

@@ -40,3 +40,14 @@ if(WITH_DEBUGTOOLS AND Corrade_TestSuite_FOUND AND NOT CORRADE_TARGET_IOS)
     target_include_directories(debugtools-compareimage PRIVATE ${CMAKE_CURRENT_BINARY_DIR})
     set_target_properties(debugtools-compareimage PROPERTIES FOLDER "Magnum/doc/snippets")
 endif()
+
+if(WITH_SDL2APPLICATION)
+    add_executable(getting-started getting-started.cpp)
+    add_executable(getting-started-blue getting-started-blue.cpp)
+    target_link_libraries(getting-started PRIVATE MagnumSdl2Application)
+    target_link_libraries(getting-started-blue PRIVATE MagnumSdl2Application)
+    set_target_properties(
+        getting-started
+        getting-started-blue
+        PROPERTIES FOLDER "Magnum/doc/snippets")
+endif()

doc/snippets/README.md

@@ -0,0 +1,11 @@
+Snippets that possibly generate output for Magnum documentation
+###############################################################
+
+### "Getting started" image
+
+Displayed by the `getting-started` executable. Run the app and take screenshot
+using Spectacle (including decorations, 880x707). Similarly for the gray
+version. The resulting files should be resized to half.
+
+The output printed by the application can be used to update the example output
+in `doc/getting-started.dox`.

doc/generated/hello.cpp → doc/snippets/getting-started-blue.cpp

@@ -23,33 +23,42 @@
     DEALINGS IN THE SOFTWARE.
 */
 
-#include <Magnum/Context.h>
 #include <Magnum/DefaultFramebuffer.h>
+#include <Magnum/Platform/Sdl2Application.h>
+/** [0] */
+#include <Magnum/Context.h>
 #include <Magnum/Renderer.h>
 #include <Magnum/Version.h>
 #include <Magnum/Math/Color.h>
-#include <Magnum/Platform/Sdl2Application.h>
+/** [0] */
 
 using namespace Magnum;
-using namespace Magnum::Math::Literals;
 
-class Hello: public Platform::Application {
-public:
-    explicit Hello(const Arguments& arguments);
+class MyApplication: public Platform::Application {
+    public:
+        explicit MyApplication(const Arguments& arguments);
 
-private:
-    void drawEvent() override;
+    private:
+        void drawEvent() override;
 };
 
-Hello::Hello(const Arguments& arguments): Platform::Application(arguments) {
-    Renderer::setClearColor(Color3::fromHSV(216.0_degf, 0.85f, 1.0f));
-    Debug() << "Hello! This application is running on" << Context::current().version()
+/** [1] */
+MyApplication::MyApplication(const Arguments& arguments): Platform::Application{arguments} {
+    using namespace Magnum::Math::Literals;
+
+    Renderer::setClearColor(0xa5c9ea_rgbf);
+
+    Debug{} << "Hello! This application is running on" << Context::current().version()
             << "using" << Context::current().rendererString();
 }
+/** [1] */
 
-void Hello::drawEvent() {
+void MyApplication::drawEvent() {
     defaultFramebuffer.clear(FramebufferClear::Color);
+
+    // TODO: Add your drawing code here
+
     swapBuffers();
 }
 
-MAGNUM_APPLICATION_MAIN(Hello)
+MAGNUM_APPLICATION_MAIN(MyApplication)

doc/snippets/getting-started.cpp

@@ -0,0 +1,53 @@
+/*
+    This file is part of Magnum.
+
+    Copyright © 2010, 2011, 2012, 2013, 2014, 2015, 2016, 2017, 2018
+              Vladimír Vondruš <mosra@centrum.cz>
+
+    Permission is hereby granted, free of charge, to any person obtaining a
+    copy of this software and associated documentation files (the "Software"),
+    to deal in the Software without restriction, including without limitation
+    the rights to use, copy, modify, merge, publish, distribute, sublicense,
+    and/or sell copies of the Software, and to permit persons to whom the
+    Software is furnished to do so, subject to the following conditions:
+
+    The above copyright notice and this permission notice shall be included
+    in all copies or substantial portions of the Software.
+
+    THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+    IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+    FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
+    THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+    LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+    FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+    DEALINGS IN THE SOFTWARE.
+*/
+
+/** [0] */
+#include <Magnum/DefaultFramebuffer.h>
+#include <Magnum/Platform/Sdl2Application.h>
+
+using namespace Magnum;
+
+class MyApplication: public Platform::Application {
+    public:
+        explicit MyApplication(const Arguments& arguments);
+
+    private:
+        void drawEvent() override;
+};
+
+MyApplication::MyApplication(const Arguments& arguments): Platform::Application{arguments} {
+    // TODO: Add your initialization code here
+}
+
+void MyApplication::drawEvent() {
+    defaultFramebuffer.clear(FramebufferClear::Color);
+
+    // TODO: Add your drawing code here
+
+    swapBuffers();
+}
+
+MAGNUM_APPLICATION_MAIN(MyApplication)
+/** [0] */