WIP: General Documentation

.github/workflows/ubuntu.yml

@@ -1,6 +1,7 @@
 name: Ubuntu
 
 on:
+  - push
   - pull_request
 
 jobs:
@@ -14,7 +15,7 @@ jobs:
       - uses: actions/checkout@v2
       - name: Downloading dependencies 📥
         run: |
-          sudo apt-get install build-essential meson libgtksourceviewmm-3.0-dev libgtkmm-3.0-dev libgtk-4-dev libgtksourceview-5-dev gi-docgen
+          sudo apt-get install build-essential meson libgtksourceviewmm-3.0-dev libgtkmm-3.0-dev libgtk-4-dev libgtksourceview-5-dev gi-docgen doxygen
           sudo apt-get install qtbase5-dev qttools5-dev-tools
       - name: Configure 🔧
         run: meson _build -DTARGET_DOCUMENTATION=true
@@ -25,11 +26,23 @@ jobs:
           pushd _build
           tar -c * | zstd -o $GITHUB_WORKSPACE/artifacts.tar.zst
           popd
+      - name: Package documentation 📜
+        run: |
+          mkdir -p pfx
+          DESTDIR=$PWD/pfx ninja -C _build install
+          pushd pfx/usr/local/share/doc/microtex/
+          tar -c * | zstd -o $GITHUB_WORKSPACE/documentation.tar.zst
+          popd
       - name: Upload build artifacts 📤
         uses: actions/upload-artifact@v1
         with:
           name: Build artifacts
           path: artifacts.tar.zst
+      - name: Upload documentation 📤
+        uses: actions/upload-artifact@v1
+        with:
+          name: Documentation
+          path: documentation.tar.zst
 
   build_by_cmake:
     runs-on: ${{ matrix.os }}

CMakeLists.txt

@@ -45,6 +45,7 @@ endif ()
 include(MicroTeXInstall.cmake)
 
 add_subdirectory(lib)
+add_subdirectory(doc)
 
 file(COPY res DESTINATION .)
 

doc/CMakeLists.txt

@@ -0,0 +1,4 @@
+set(cwd ${CMAKE_CURRENT_LIST_DIR})
+set(source_root ${microtex_SOURCE_DIR})
+set(version ${microtex_VERSION})
+configure_file(microtex.doxy.in microtex.doxy @ONLY)

doc/cairodoc.h

@@ -0,0 +1,46 @@
+/** \page cairo_doc Cairo Documentation
+ *
+ * \section cairo_opts Build options
+ *
+ * \subsection Meson
+ * to build support for the Cairo platform using meson, you need to
+ * invoke meson using <tt>-DCAIRO=true</tt> as parameter.
+ *
+ * If you want to build the GTK3MM demo too, you need to add the
+ * <tt>-DEXAMPLE_GTKMM=true</tt> to the params too.
+ *
+ * \subsection CMake
+ *
+ * for cmake, you need to configure it, with <tt>-DCAIRO=ON</tt>
+ * and optionally with <tt>-DBUILD_EXAMPLE_GTKMM=ON</tt>.
+ *
+ * \section cairo_usage Usage
+ *
+ * \subsection cairo_init Initialization and PlatformFactory setup
+ * Refer to \ref index "the main page" for info about information about automatic
+ * font detection. The PlatformFactory setup is cairo specific.
+ * @code
+ *  microtex::InitFontSenseAuto autoinit;
+ *  microtex::MicroTeX::init(autoinit);
+ *  microtex::PlatformFactory::registerFactory("gtk", std::make_unique<microtex::PlatformFactory_cairo>());
+ *  microtex::PlatformFactory::activate("gtk");
+ * @endcode
+ *
+ * \subsection cairo_render Rendering
+ * You need to make use of microtex::Graphics2D_cairo to render
+ * equations onto a cairo surface. The graphics context takes a pointer
+ * to a cairo context (<tt>cairo_t</tt>). Please note that the caller
+ * keeps the ownership of the cairo context.
+ *
+ * To receive a microtex::Render, you can either use the convenience
+ * method microtex::MicroTeX::parse(), or construct it yourself using
+ * microtex::RenderBuilder if you need more customization.
+ *
+ * @code
+ *   void render_to_cairo(cairo_t* ctx, microtex::Render* tex) {
+ *     microtex::Graphics2D_cairo g2(ctx);
+ *     tex->draw(g2, 0, 0);
+ *   }  
+ * @endcode
+ *
+ */