From 352f494bee72095606ea9dbfbade1dcad8e43584 Mon Sep 17 00:00:00 2001 From: sithlord48 Date: Sat, 25 Jul 2026 11:55:14 -0400 Subject: [PATCH] docs: Pack in markdown for use in help viewer, remove user docs as they are now normal docs to ship removes need for doxygen to build general documents --- .../actions/install-dependencies/action.yml | 24 ++----- .github/workflows/continuous-integration.yml | 8 +-- .../linux/flatpak/org.deskflow.deskflow.yml | 1 - docs/CMakeLists.txt | 59 +++++++++++------- .../configuration.md => Configuration.md} | 1 - docs/HelpMain.md | 24 +++++++ docs/Issues.md | 24 +++++++ docs/dev/CMakeLists.txt | 46 +++++++++----- docs/dev/build.md | 1 - docs/{ => dev}/deskflow-logo.png | Bin docs/user/CMakeLists.txt | 19 ------ docs/user/mainpage.md | 14 ----- src/lib/gui/MainWindow.cpp | 15 +++-- 13 files changed, 126 insertions(+), 110 deletions(-) rename docs/{user/configuration.md => Configuration.md} (99%) create mode 100644 docs/HelpMain.md create mode 100644 docs/Issues.md rename docs/{ => dev}/deskflow-logo.png (100%) delete mode 100644 docs/user/CMakeLists.txt delete mode 100644 docs/user/mainpage.md diff --git a/.github/actions/install-dependencies/action.yml b/.github/actions/install-dependencies/action.yml index a8c87e209..137b2002d 100644 --- a/.github/actions/install-dependencies/action.yml +++ b/.github/actions/install-dependencies/action.yml @@ -30,24 +30,24 @@ runs: if: ${{ runner.os != 'Windows' }} run: | if [ "$RUNNER_OS" == "macOS" ]; then - brew install openssl doxygen --quiet + brew install openssl --quiet elif [ "$RUNNER_OS" == "Linux" ]; then if [ ${{inputs.like}} == "debian" ]; then apt update -qqq > /dev/null apt install -qqq cmake build-essential ninja-build \ xorg-dev libx11-dev libxtst-dev libssl-dev \ libxkbfile-dev qt6-base-dev qt6-tools-dev libxkbcommon-dev \ - libei-dev libportal-dev help2man doxygen -y >/dev/null + libei-dev libportal-dev help2man -y >/dev/null elif [ ${{inputs.like}} == "fedora" ]; then dnf install -y cmake make ninja-build gcc-c++ rpm-build openssl-devel \ libXtst-devel libxkbfile-devel qt6-qtbase-devel qt6-qttools-devel libxkbcommon-x11-devel \ - libei-devel libxkbcommon-devel libportal-devel help2man doxygen libXinerama-devel libXrandr-devel + libei-devel libxkbcommon-devel libportal-devel help2man libXinerama-devel libXrandr-devel elif [ ${{inputs.like}} == "suse" ]; then zypper refresh zypper install -y --force-resolution \ cmake make ninja gcc-c++ rpm-build libopenssl-devel \ libXtst-devel libxkbfile-devel qt6-base-devel qt6-tools-devel \ - qt6-linguist-devel doxygen libxkbcommon-devel libxkbcommon-x11-devel \ + qt6-linguist-devel libxkbcommon-devel libxkbcommon-x11-devel \ libei-devel libportal-devel help2man libXinerama-devel libXrandr-devel elif [ ${{ inputs.like }} == "arch" ]; then pacman -Syu --noconfirm base-devel cmake ninja \ @@ -82,22 +82,6 @@ runs: token: ${{ github.token }} revision: master - - name: Cache Chocolatey - id: cache-choco - if: (runner.os == 'Windows') - uses: actions/cache@v5 - with: - path: | - C:/ProgramData/chocolatey/bin/ - C:/ProgramData/chocolatey/lib/doxygen.install - C:/Program*/doxygen/ - key: cache-chocolatey${{ matrix.config.arch }}-doxygen - - - name: Install doxygen (windows) - if: ((runner.os == 'Windows') && (steps.cache-choco.outputs.cache-hit != 'true')) - shell: bash - run: choco install doxygen.install - - name: Install Wix if: ${{ runner.os == 'Windows' }} run: | diff --git a/.github/workflows/continuous-integration.yml b/.github/workflows/continuous-integration.yml index 5f7028b66..5c55d6bea 100644 --- a/.github/workflows/continuous-integration.yml +++ b/.github/workflows/continuous-integration.yml @@ -257,11 +257,6 @@ jobs: - name: Get version uses: ./.github/actions/get-version - - name: Update Windows Paths - if: (runner.os == 'Windows') - shell: pwsh - run: echo "C:\Program Files\doxygen\bin" | Out-File -FilePath $env:GITHUB_PATH -Encoding utf8 -Append - - name: Configure run: ${{env.CMAKE_CONFIGURE}} ${{ matrix.target.config-args }} ${{ steps.get-deps.outputs.vcpkg-cmake-config }} -DPACKAGE_VERSION_LABEL="${{env.DESKFLOW_PACKAGE_VERSION}}" @@ -360,8 +355,7 @@ jobs: run: | pkg install -y cmake ninja gmake gcc12 openssl libXrandr libXinerama \ - libX11 libXtst libxkbfile qt6-base qt6-tools libxkbcommon pkgconf libei \ - libportal doxygen + libX11 libXtst libxkbfile qt6-base qt6-tools libxkbcommon pkgconf libei libportal ${{env.CMAKE_CONFIGURE}} -G Ninja cmake --build build -j16 flatpak: diff --git a/deploy/linux/flatpak/org.deskflow.deskflow.yml b/deploy/linux/flatpak/org.deskflow.deskflow.yml index dad2339e4..6100a3761 100644 --- a/deploy/linux/flatpak/org.deskflow.deskflow.yml +++ b/deploy/linux/flatpak/org.deskflow.deskflow.yml @@ -18,7 +18,6 @@ cleanup: - /lib/pkgconfig - /share/pkgconfig - /share/cmake - - /share/doc - /share/gir-1.0 - /lib/girepository-1.0 modules: diff --git a/docs/CMakeLists.txt b/docs/CMakeLists.txt index fb32d2ba7..60d2bf6af 100644 --- a/docs/CMakeLists.txt +++ b/docs/CMakeLists.txt @@ -1,35 +1,46 @@ -# SPDX-FileCopyrightText: (C) 2019 - 2025 Chris Rizzitello +# SPDX-FileCopyrightText: (C) 2019 - 2026 Chris Rizzitello # SPDX-License-Identifier: MIT -find_package(Doxygen QUIET) -option(BUILD_USER_DOCS "Build and install user documentation" ${DOXYGEN_FOUND}) + option(BUILD_DEV_DOCS "Build and install developer documentation" OFF) - -if (DOXYGEN_FOUND) - # Generic Doxygen options - set(DOXYGEN_EXTRACT_ALL YES) - set(DOXYGEN_EXTRACT_STATIC YES) - set(DOXYGEN_STRIP_FROM_PATH ${CMAKE_SOURCE_DIR}) - set(DOXYGEN_QUIET YES) - set(DOXYGEN_PROJECT_NAME ${CMAKE_PROJECT_PROPER_NAME}) - set(DOXYGEN_PROJECT_ICON "${CMAKE_CURRENT_SOURCE_DIR}/deskflow-logo.png") - set(DOXYGEN_PROJECT_LOGO "${CMAKE_CURRENT_SOURCE_DIR}/deskflow-logo.png") - - if (BUILD_USER_DOCS) - add_subdirectory(user) - endif() - if (BUILD_DEV_DOCS) - add_subdirectory(dev) - endif() -else() - message(STATUS "Doxygen not found, skipping docs build") +if (BUILD_DEV_DOCS) + add_subdirectory(dev) endif() # Show our documents in the IDE -add_custom_target(docs +add_custom_target(docs ALL SOURCES Readme.md Security.md + HelpMain.md + Configuration.md + Issues.md +) + +install( + FILES + Readme.md + HelpMain.md + Configuration.md + Issues.md + Security.md + DESTINATION ${CMAKE_INSTALL_DOCDIR} +) + +# Make sure that help docs are moved. +add_custom_command( + TARGET docs PRE_BUILD + COMMAND ${CMAKE_COMMAND} -E copy_if_different + ${CMAKE_CURRENT_SOURCE_DIR}/HelpMain.md + ${CMAKE_CURRENT_BINARY_DIR}/HelpMain.md + COMMAND ${CMAKE_COMMAND} -E copy_if_different + ${CMAKE_CURRENT_SOURCE_DIR}/Configuration.md + ${CMAKE_CURRENT_BINARY_DIR}/Configuration.md + COMMAND ${CMAKE_COMMAND} -E copy_if_different + ${CMAKE_CURRENT_SOURCE_DIR}/Issues.md + ${CMAKE_CURRENT_BINARY_DIR}/Issues.md + COMMAND ${CMAKE_COMMAND} -E copy_if_different + ${CMAKE_CURRENT_SOURCE_DIR}/Security.md + ${CMAKE_CURRENT_BINARY_DIR}/Security.md ) -install(FILES Security.md Readme.md DESTINATION ${CMAKE_INSTALL_DOCDIR}) diff --git a/docs/user/configuration.md b/docs/Configuration.md similarity index 99% rename from docs/user/configuration.md rename to docs/Configuration.md index 54f948820..564723c13 100644 --- a/docs/user/configuration.md +++ b/docs/Configuration.md @@ -2,7 +2,6 @@ Deskflow will automatically figure out where to save settings and other files. - ## Search paths Deskflow will look for settings in several places depending on your operating system. diff --git a/docs/HelpMain.md b/docs/HelpMain.md new file mode 100644 index 000000000..8d768cd79 --- /dev/null +++ b/docs/HelpMain.md @@ -0,0 +1,24 @@ +Welcome to the Deskflow Help! + +## Introduction +* [Homepage](https://deskflow.org) - Project home page +* [Code](https://github.com/deskflow/deskflow) - Read the code + +## User Guides +* [Configuration] - Configuration files +* [Raising Issues] - What to do if you have found an issue. +* [Security Policy] - Our policy around security related topics + +## Getting help online + +* View the [Wiki](https://github.com/deskflow/deskflow/wiki) Online resource + +### Chat with us +* Main discussion on Matrix: [`#deskflow:matrix.org`](https://matrix.to/#/#deskflow:matrix.org) ([Matrix clients](https://matrix.org/ecosystem/clients/)) +* Discussion also happens on IRC: `#deskflow` or `#deskflow-dev` on [Libera Chat](https://libera.chat/) +* Start a [new discussion](https://github.com/deskflow/deskflow/discussions) on our GitHub project. + +[Configuration]:Configuration.md +[Raising Issues]:Issues.md +[Security Policy]:Security.md + diff --git a/docs/Issues.md b/docs/Issues.md new file mode 100644 index 000000000..69c32e47b --- /dev/null +++ b/docs/Issues.md @@ -0,0 +1,24 @@ +## Important + If your having an issue. Always try the [continuous](https://github.com/deskflow/deskflow/releases/tag/continuous) version.
+ Many bugs are fixed between releases and yours could be one of them. + +## Note + When providing version information always use the copy button on the about dialog.
+ This will include the version as well as the OS Type OS Version, Processor Architecture, and session type + +### If You have Found an issue not fixed by continuous + +Check the existing [issues](https://github.com/deskflow/deskflow/issues?q=is%3Aissue) to see if someone has reported the issue your experiencing. When searching include closed issues as they may regression, the issue be resolved or be misunderstanding. + +If a matching or similar issues exists there is no need to comment unless your comment add new information to help solve the bug. An example of a useful comment could be your platform not matching the reporters if an issues is said to be on a specific platform only. We would like to keep the issues comments on topic and uncluttered as some issues can take some time and much discussion to resolve. In most cases you should only :+1: to the issues description. + +### Creating new issues + + When in doubt start by [asking a question](https://github.com/deskflow/deskflow/discussions/new?category=q-a) + + 1. Enable debug level in your log to capture the log the next time the issue happens. + 1. Create A [New Issue](https://github.com/deskflow/deskflow/issues/new/choose) + 1. When reporting issues make sure you include the initial version tested as well as the version of the continuous used when testing. Use the about dialogs copy button to get this information. + 1. Include logs when reporting + 1. Use `

TITLE

` tags to wrap logs and other lengthy blocks so they are collapse-able + 1. Fill out the bug form completely, when relevant include info about the both server and clients diff --git a/docs/dev/CMakeLists.txt b/docs/dev/CMakeLists.txt index ac06a109d..ef60cb317 100644 --- a/docs/dev/CMakeLists.txt +++ b/docs/dev/CMakeLists.txt @@ -1,22 +1,34 @@ -# SPDX-FileCopyrightText: (C) 2025 Chris Rizzitello +# SPDX-FileCopyrightText: (C) 2025 - 2026 Chris Rizzitello # SPDX-License-Identifier: MIT -set(DOXYGEN_USE_MDFILE_AS_MAINPAGE mainpage.md) -set(DOXYGEN_EXCLUDE_PATTERNS "*unittests/*") -set(DOXYGEN_DOT_GRAPH_MAX_NODES 100) +find_package(Doxygen QUIET) +if (DOXYGEN_FOUND) + # Generic Doxygen options + set(DOXYGEN_EXTRACT_ALL YES) + set(DOXYGEN_EXTRACT_STATIC YES) + set(DOXYGEN_STRIP_FROM_PATH ${CMAKE_SOURCE_DIR}) + set(DOXYGEN_QUIET YES) + set(DOXYGEN_PROJECT_NAME ${CMAKE_PROJECT_PROPER_NAME}) + set(DOXYGEN_PROJECT_ICON "${CMAKE_CURRENT_SOURCE_DIR}/deskflow-logo.png") + set(DOXYGEN_PROJECT_LOGO "${CMAKE_CURRENT_SOURCE_DIR}/deskflow-logo.png") + set(DOXYGEN_USE_MDFILE_AS_MAINPAGE mainpage.md) + set(DOXYGEN_EXCLUDE_PATTERNS "*unittests/*") + set(DOXYGEN_DOT_GRAPH_MAX_NODES 100) -# Files used to make our documents -doxygen_add_docs(dev-docs - ${CMAKE_CURRENT_SOURCE_DIR} - ${CMAKE_SOURCE_DIR}/src - COMMENT "Generating developer documentation" ALL) + # Files used to make our documents + doxygen_add_docs(dev-docs + ${CMAKE_CURRENT_SOURCE_DIR} + ${CMAKE_SOURCE_DIR}/src + COMMENT "Generating developer documentation" ALL) -# HACK Only these will show in your IDE -target_sources(dev-docs PRIVATE - mainpage.md - contributing.md - build.md - protocol_reference.md -) + # HACK Only these will show in your IDE + target_sources(dev-docs PRIVATE + mainpage.md + contributing.md + build.md + protocol_reference.md + ) +else() + message(STATUS "Doxygen not found, skipping docs build") +endif() -# missing install target is intended generate a local copy diff --git a/docs/dev/build.md b/docs/dev/build.md index 71fc88576..01d3b2549 100644 --- a/docs/dev/build.md +++ b/docs/dev/build.md @@ -21,7 +21,6 @@ Deskflow supports the following CMake options: | Option | Description | Default Value | Additional requirements | :-------------------------:|:---------------------------------------:|:------------------:|:-----------------------:| -| BUILD_USER_DOCS | Build user documentation | DOXYGEN_FOUND | `Doxygen` | | BUILD_DEV_DOCS | Build development documentation | OFF | `Doxygen` | | BUILD_INSTALLER | Build installers/packages | ON | | | BUILD_TESTS | Build unit tests and legacy tests | ON | | diff --git a/docs/deskflow-logo.png b/docs/dev/deskflow-logo.png similarity index 100% rename from docs/deskflow-logo.png rename to docs/dev/deskflow-logo.png diff --git a/docs/user/CMakeLists.txt b/docs/user/CMakeLists.txt deleted file mode 100644 index 396ad1735..000000000 --- a/docs/user/CMakeLists.txt +++ /dev/null @@ -1,19 +0,0 @@ -# SPDX-FileCopyrightText: (C) 2025 Chris Rizzitello -# SPDX-License-Identifier: MIT - -set(DOXYGEN_USE_MDFILE_AS_MAINPAGE mainpage.md) - -# Files used to make our documents -# User facing documents will not include doxy comments in source code -doxygen_add_docs(user-docs ${CMAKE_CURRENT_SOURCE_DIR} COMMENT "Generating user documentation" ALL) - -# HACK Only these will show in your IDE -target_sources(user-docs PRIVATE - mainpage.md - configuration.md -) - -install( - DIRECTORY "${CMAKE_CURRENT_BINARY_DIR}/html" - DESTINATION ${CMAKE_INSTALL_DOCDIR} -) diff --git a/docs/user/mainpage.md b/docs/user/mainpage.md deleted file mode 100644 index fd7226aef..000000000 --- a/docs/user/mainpage.md +++ /dev/null @@ -1,14 +0,0 @@ -**Deskflow** is a free and open source keyboard and mouse sharing app. -Use the keyboard, mouse, or trackpad of one computer to control nearby computers, -and work seamlessly between them. - - -## Configuration -Our [Configuration] page has example configurations - - -## More info - -For more info, see our [Wiki](https://github.com/deskflow/deskflow/wiki). - -[Configuration]:configuration.md diff --git a/src/lib/gui/MainWindow.cpp b/src/lib/gui/MainWindow.cpp index 885604a1f..759b427ca 100644 --- a/src/lib/gui/MainWindow.cpp +++ b/src/lib/gui/MainWindow.cpp @@ -1295,13 +1295,16 @@ void MainWindow::updateTimeoutDelay(int newDelay) void MainWindow::setHelpFilePath() { const QString appPath = QCoreApplication::applicationDirPath(); - const auto buildPath = QDir::cleanPath(QString("%1/../docs/user/html/index.html").arg(appPath)); - auto installPath = QString("%1/../share/doc/deskflow/html/index.html").arg(appPath); - if (deskflow::platform::isMac()) - installPath = QString("%1/Contents/Resources/docs/html/index.html").arg(appPath); - else if (deskflow::platform::isWindows()) - installPath = QString("%1/docs/html/index.html").arg(appPath); + auto buildPath = QString("%1/../docs/HelpMain.md").arg(appPath); + auto installPath = QString("%1/../share/doc/%2/HelpMain.md").arg(appPath, kAppId); + if (deskflow::platform::isMac()) { + installPath = QString("%1/../Resources/docs/HelpMain.md").arg(appPath); + buildPath = QString("%1/../../../../docs/HelpMain.md").arg(appPath); + } else if (deskflow::platform::isWindows()) { + installPath = QString("%1/docs/HelpMain.md").arg(appPath); + } + buildPath = QDir::cleanPath(buildPath); installPath = QDir::cleanPath(installPath); if (QFile::exists(installPath))