From a40a54ec105fb5900bff77e13e49f799c66c2dc6 Mon Sep 17 00:00:00 2001 From: Tushar Maheshwari Date: Fri, 23 Jul 2021 12:10:47 +0530 Subject: [PATCH] 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 | 34 ++++++++++++++ doc/CMakeLists.txt | 15 ++++-- doc/Doxyfile.in | 22 +++++---- doc/example_list.md | 46 ------------------- examples/dom/package_manager.cpp | 2 - include/ftxui/component/component_options.hpp | 32 ++++++------- tools/format.sh | 8 ---- 7 files changed, 72 insertions(+), 87 deletions(-) create mode 100644 .github/workflows/documentation.yaml delete mode 100644 doc/example_list.md diff --git a/.github/workflows/documentation.yaml b/.github/workflows/documentation.yaml new file mode 100644 index 0000000..5570bb6 --- /dev/null +++ b/.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 diff --git a/doc/CMakeLists.txt b/doc/CMakeLists.txt index 0409dab..b47de23 100644 --- a/doc/CMakeLists.txt +++ b/doc/CMakeLists.txt @@ -1,10 +1,15 @@ find_package(Doxygen) if (DOXYGEN_FOUND) - configure_file( - ${CMAKE_CURRENT_SOURCE_DIR}/Doxyfile.in - ${CMAKE_CURRENT_BINARY_DIR}/Doxyfile - @ONLY - ) + # Generate example list for documentation + set(EXAMPLE_LIST "${CMAKE_CURRENT_BINARY_DIR}/example_list.md") + file(WRITE ${EXAMPLE_LIST} "# Examples") + 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 diff --git a/doc/Doxyfile.in b/doc/Doxyfile.in index 0d743af..8b60362 100644 --- a/doc/Doxyfile.in +++ b/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 += @CMAKE_CURRENT_SOURCE_DIR@/../src/ +INPUT += @PROJECT_SOURCE_DIR@/include +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 += @CMAKE_CURRENT_SOURCE_DIR@/../include/ -EXAMPLE_PATH += @CMAKE_CURRENT_SOURCE_DIR@/../src/ +EXAMPLE_PATH += @PROJECT_SOURCE_DIR@/examples +EXAMPLE_PATH += @PROJECT_SOURCE_DIR@/include +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 @CMAKE_CURRENT_SOURCE_DIR@/../src/ -CLANG_OPTIONS += --include-directory @CMAKE_CURRENT_SOURCE_DIR@/../examples/ +CLANG_OPTIONS += --include-directory @PROJECT_SOURCE_DIR@/include +CLANG_OPTIONS += --include-directory @PROJECT_SOURCE_DIR@/src +CLANG_OPTIONS += --include-directory @PROJECT_SOURCE_DIR@/examples CLANG_OPTIONS += -std=c++17 #--------------------------------------------------------------------------- diff --git a/doc/example_list.md b/doc/example_list.md deleted file mode 100644 index 9405532..0000000 --- a/doc/example_list.md +++ /dev/null @@ -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 diff --git a/examples/dom/package_manager.cpp b/examples/dom/package_manager.cpp index 1ae23b3..d2c0d74 100644 --- a/examples/dom/package_manager.cpp +++ b/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; diff --git a/include/ftxui/component/component_options.hpp b/include/ftxui/component/component_options.hpp index f24e044..34dc295 100644 --- a/include/ftxui/component/component_options.hpp +++ b/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_focused = inverted; /// Style when focused. - Decorator style_selected = bold; /// Style when selected. + Decorator style_normal = nothing; ///< style. + Decorator style_focused = inverted; ///< Style when focused. + 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 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_unchecked = L"☐ "; /// Prefix for a "unchecked" state. - Decorator style_focused = inverted; /// Decorator used when focused. - Decorator style_unfocused = nothing; /// Decorator used when unfocused. + std::wstring style_checked = L"▣ "; ///< Prefix for a "checked" state. + std::wstring style_unchecked = L"☐ "; ///< Prefix for a "unchecked" state. + Decorator style_focused = inverted; ///< Decorator used when focused. + Decorator style_unfocused = nothing; ///< Decorator used when unfocused. /// Called when the user change the state. std::function 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_unchecked = L"○ "; /// Prefix for a "unchecked" state. - Decorator style_focused = inverted; /// Decorator used when focused. - Decorator style_unfocused = nothing; /// Decorator used when unfocused. + std::wstring style_checked = L"◉ "; ///< Prefix for a "checked" state. + std::wstring style_unchecked = L"○ "; ///< Prefix for a "unchecked" state. + Decorator style_focused = inverted; ///< Decorator used when focused. + Decorator style_unfocused = nothing; ///< Decorator used when unfocused. /// Called when the selected entry changes. std::function 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_focused = inverted; /// Style when focused. - Decorator style_selected = bold; /// Style when selected. + Decorator style_normal = nothing; ///< style. + Decorator style_focused = inverted; ///< Style when focused. + 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 on_change = [] {}; diff --git a/tools/format.sh b/tools/format.sh index 8c46506..ec36dee 100755 --- a/tools/format.sh +++ b/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