Improve documentation workflow (#163)

* Compact project relative paths from doc directory

* Remove committed example_list.md

- generate example_list from cmake for documentation

* Fix doxygen same-line comments

* Add workflow for generating documentation

.github/workflows/documentation.yaml

@@ -0,0 +1,34 @@
+name: Documentation
+
+# Triggers the workflow on push events only for the master branch
+on:
+  push:
+    branches: [ master ]
+
+jobs:
+  build-documentation:
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@v2
+
+    - name: Install Doxygen
+      run: |
+        sudo apt-get update
+        sudo apt-get install doxygen
+
+    - name: Build HTML documentation
+      run: |
+        cmake -S . -B build
+        cmake --build build --target doc
+
+    # Deploy the HTML documentation to GitHub Pages
+    - name: GH Pages Deployment
+      uses: peaceiris/actions-gh-pages@v3
+      with:
+        github_token: ${{ secrets.GITHUB_TOKEN }}
+        publish_dir: build/doc/doxygen/html/
+        enable_jekyll: false
+        allow_empty_commit: false
+        force_orphan: true
+        publish_branch: gh-pages

doc/CMakeLists.txt

@@ -1,10 +1,15 @@
 find_package(Doxygen)
 if (DOXYGEN_FOUND)
-  configure_file(
+  # Generate example list for documentation
-    ${CMAKE_CURRENT_SOURCE_DIR}/Doxyfile.in
+  set(EXAMPLE_LIST "${CMAKE_CURRENT_BINARY_DIR}/example_list.md")
-    ${CMAKE_CURRENT_BINARY_DIR}/Doxyfile
+  file(WRITE ${EXAMPLE_LIST} "# Examples")
-    @ONLY
+  file(GLOB_RECURSE EXAMPLES RELATIVE ${PROJECT_SOURCE_DIR}
-    )
+    "${PROJECT_SOURCE_DIR}/examples/*.cpp")
+  foreach(EXAMPLE IN LISTS EXAMPLES)
+    file(APPEND ${EXAMPLE_LIST} "\n@example ${EXAMPLE}")
+  endforeach(EXAMPLE IN LISTS EXAMPLES)
+
+  configure_file(Doxyfile.in Doxyfile @ONLY)
 
   # note the option ALL which allows to build the docs together with the application
   add_custom_target(doc

doc/Doxyfile.in

@@ -38,7 +38,7 @@ PROJECT_NAME           = "FTXUI"
 # could be handy for archiving the generated documentation or if some version
 # control system is used.
 
-PROJECT_NUMBER         = @CMAKE_PROJECT_VERSION@
+PROJECT_NUMBER         = @PROJECT_VERSION@
 
 # Using the PROJECT_BRIEF tag one can provide an optional one line description
 # for a project that appears at the top of each page and should give viewer a
@@ -162,7 +162,8 @@ FULL_PATH_NAMES        = YES
 # will be relative from the directory where doxygen is started.
 # This tag requires that the tag FULL_PATH_NAMES is set to YES.
 
-STRIP_FROM_PATH        = ../..
+STRIP_FROM_PATH        = @PROJECT_SOURCE_DIR@ \
+                         @PROJECT_BINARY_DIR@
 
 # The STRIP_FROM_INC_PATH tag can be used to strip a user-defined part of the
 # path mentioned in the documentation of a class, which tells the reader which
@@ -783,9 +784,10 @@ WARN_LOGFILE           =
 # spaces. See also FILE_PATTERNS and EXTENSION_MAPPING
 # Note: If this tag is empty the current directory is searched.
 
-INPUT                 += @CMAKE_CURRENT_SOURCE_DIR@/../include/
+INPUT                 += @PROJECT_SOURCE_DIR@/include
-INPUT                 += @CMAKE_CURRENT_SOURCE_DIR@/../src/
+INPUT                 += @PROJECT_SOURCE_DIR@/src
 INPUT                 += @CMAKE_CURRENT_SOURCE_DIR@
+INPUT                 += @EXAMPLE_LIST@
 
 # This tag can be used to specify the character encoding of the source files
 # that doxygen parses. Internally doxygen uses the UTF-8 encoding. Doxygen uses
@@ -902,9 +904,9 @@ EXCLUDE_SYMBOLS        =
 # that contain example code fragments that are included (see the \include
 # command).
 
-EXAMPLE_PATH           += @CMAKE_CURRENT_SOURCE_DIR@/../examples/
+EXAMPLE_PATH           += @PROJECT_SOURCE_DIR@/examples
-EXAMPLE_PATH           += @CMAKE_CURRENT_SOURCE_DIR@/../include/
+EXAMPLE_PATH           += @PROJECT_SOURCE_DIR@/include
-EXAMPLE_PATH           += @CMAKE_CURRENT_SOURCE_DIR@/../src/
+EXAMPLE_PATH           += @PROJECT_SOURCE_DIR@/src
 
 # If the value of the EXAMPLE_PATH tag contains directories, you can use the
 # EXAMPLE_PATTERNS tag to specify one or more wildcard pattern (like *.cpp and
@@ -1085,9 +1087,9 @@ CLANG_ASSISTED_PARSING = NO
 # specified with INPUT and INCLUDE_PATH.
 # This tag requires that the tag CLANG_ASSISTED_PARSING is set to YES.
 
-CLANG_OPTIONS          += --include-directory @CMAKE_CURRENT_SOURCE_DIR@/../include/
+CLANG_OPTIONS          += --include-directory @PROJECT_SOURCE_DIR@/include
-CLANG_OPTIONS          += --include-directory @CMAKE_CURRENT_SOURCE_DIR@/../src/
+CLANG_OPTIONS          += --include-directory @PROJECT_SOURCE_DIR@/src
-CLANG_OPTIONS          += --include-directory @CMAKE_CURRENT_SOURCE_DIR@/../examples/
+CLANG_OPTIONS          += --include-directory @PROJECT_SOURCE_DIR@/examples
 CLANG_OPTIONS          += -std=c++17
 
 #---------------------------------------------------------------------------

doc/example_list.md

@@ -1,46 +0,0 @@
-# Examples
-@example ./examples/component/button.cpp
-@example ./examples/component/checkbox.cpp
-@example ./examples/component/checkbox_in_frame.cpp
-@example ./examples/component/composition.cpp
-@example ./examples/component/gallery.cpp
-@example ./examples/component/homescreen.cpp
-@example ./examples/component/input.cpp
-@example ./examples/component/menu2.cpp
-@example ./examples/component/menu.cpp
-@example ./examples/component/menu_multiple.cpp
-@example ./examples/component/menu_style.cpp
-@example ./examples/component/modal_dialog.cpp
-@example ./examples/component/radiobox.cpp
-@example ./examples/component/radiobox_in_frame.cpp
-@example ./examples/component/resizable_split.cpp
-@example ./examples/component/slider.cpp
-@example ./examples/component/slider_rgb.cpp
-@example ./examples/component/tab_horizontal.cpp
-@example ./examples/component/tab_vertical.cpp
-@example ./examples/component/toggle.cpp
-@example ./examples/dom/border.cpp
-@example ./examples/dom/color_gallery.cpp
-@example ./examples/dom/color_info_palette256.cpp
-@example ./examples/dom/color_truecolor_HSV.cpp
-@example ./examples/dom/color_truecolor_RGB.cpp
-@example ./examples/dom/dbox.cpp
-@example ./examples/dom/gauge.cpp
-@example ./examples/dom/graph.cpp
-@example ./examples/dom/hflow.cpp
-@example ./examples/dom/html_like.cpp
-@example ./examples/dom/package_manager.cpp
-@example ./examples/dom/paragraph.cpp
-@example ./examples/dom/separator.cpp
-@example ./examples/dom/size.cpp
-@example ./examples/dom/spinner.cpp
-@example ./examples/dom/style_blink.cpp
-@example ./examples/dom/style_bold.cpp
-@example ./examples/dom/style_color.cpp
-@example ./examples/dom/style_dim.cpp
-@example ./examples/dom/style_gallery.cpp
-@example ./examples/dom/style_inverted.cpp
-@example ./examples/dom/style_underlined.cpp
-@example ./examples/dom/vbox_hbox.cpp
-@example ./examples/dom/window.cpp
-@example ./examples/util/print_key_press.cpp

examples/dom/package_manager.cpp

@@ -14,8 +14,6 @@
 #include "ftxui/screen/box.hpp"
 #include "ftxui/screen/color.hpp"
 
-/// @example examples/dom/package_manage.cpp
-
 int main(int argc, const char* argv[]) {
   using namespace ftxui;
 

include/ftxui/component/component_options.hpp

@@ -9,11 +9,11 @@ namespace ftxui {
 /// @brief Option for the Menu component.
 /// @ingroup component
 struct MenuOption {
-  Decorator style_normal = nothing;    /// style.
+  Decorator style_normal = nothing;    ///< style.
-  Decorator style_focused = inverted;  /// Style when focused.
+  Decorator style_focused = inverted;  ///< Style when focused.
-  Decorator style_selected = bold;     /// Style when selected.
+  Decorator style_selected = bold;     ///< Style when selected.
   Decorator style_selected_focused =
-      Decorator(inverted) | bold;  /// Style when selected and focused.
+      Decorator(inverted) | bold;  ///< Style when selected and focused.
 
   /// Called when the selected entry changes.
   std::function<void()> on_change = [] {};
@@ -33,10 +33,10 @@ struct ButtonOption {
 /// @brief Option for the Checkbox component.
 /// @ingroup component
 struct CheckboxOption {
-  std::wstring style_checked = L"▣ ";    /// Prefix for a "checked" state.
+  std::wstring style_checked = L"▣ ";    ///< Prefix for a "checked" state.
-  std::wstring style_unchecked = L"☐ ";  /// Prefix for a "unchecked" state.
+  std::wstring style_unchecked = L"☐ ";  ///< Prefix for a "unchecked" state.
-  Decorator style_focused = inverted;    /// Decorator used when focused.
+  Decorator style_focused = inverted;    ///< Decorator used when focused.
-  Decorator style_unfocused = nothing;   /// Decorator used when unfocused.
+  Decorator style_unfocused = nothing;   ///< Decorator used when unfocused.
 
   /// Called when the user change the state.
   std::function<void()> on_change = []() {};
@@ -59,10 +59,10 @@ struct InputOption {
 /// @brief Option for the Radiobox component.
 /// @ingroup component
 struct RadioboxOption {
-  std::wstring style_checked = L"◉ ";    /// Prefix for a "checked" state.
+  std::wstring style_checked = L"◉ ";    ///< Prefix for a "checked" state.
-  std::wstring style_unchecked = L"○ ";  /// Prefix for a "unchecked" state.
+  std::wstring style_unchecked = L"○ ";  ///< Prefix for a "unchecked" state.
-  Decorator style_focused = inverted;    /// Decorator used when focused.
+  Decorator style_focused = inverted;    ///< Decorator used when focused.
-  Decorator style_unfocused = nothing;   /// Decorator used when unfocused.
+  Decorator style_unfocused = nothing;   ///< Decorator used when unfocused.
 
   /// Called when the selected entry changes.
   std::function<void()> on_change = []() {};
@@ -73,11 +73,11 @@ struct RadioboxOption {
 /// @brief Option for the Toggle component.
 /// @ingroup component
 struct ToggleOption {
-  Decorator style_normal = nothing;    /// style.
+  Decorator style_normal = nothing;    ///< style.
-  Decorator style_focused = inverted;  /// Style when focused.
+  Decorator style_focused = inverted;  ///< Style when focused.
-  Decorator style_selected = bold;     /// Style when selected.
+  Decorator style_selected = bold;     ///< Style when selected.
   Decorator style_selected_focused =
-      Decorator(inverted) | bold;  /// Style when selected and focused.
+      Decorator(inverted) | bold;  ///< Style when selected and focused.
 
   /// Called when the selected entry changes.
   std::function<void()> on_change = [] {};

tools/format.sh

@@ -17,11 +17,3 @@ for file in $files
 do
   clang-format -i $file
 done
-
-exampleList="./doc/example_list.md"
-echo "# Examples" > $exampleList
-files=$(find ./examples -iname "*.cpp" | sort)
-for f in $files
-do
-  echo "@example $f" >> $exampleList
-done