[FL-870] Auto-generated firmware documentation take two (#2944)

* Add doxygen and doxygen-awesome css, cleanup docs files * Ignore more libraries and remove leftover local variables * Create an actual intro page * .md files linting * Add doxygen action * Fix Doxygen path * Fix doxyfile path * Try to upload * Change docs branch * Add submudules checkout * Disable doxygen on PR * Mention the firmware docs in the readme * More dev docs mentions in the readme * Fix runner group, add tags * Test dev in PR * Disable running on PR * Fix a typo in the doxyfile * Try upload to S3 * Fix local path * Fix S3 ACL * Add delete flag, unifying dev and tags * Update ignored directories * More ignored directories * Even more ignored directories * Fix submodule * Change S3 uploader * Change S3 uploader version * Fix aws sync flags * Fix ACL * Disable ACL * Improve ignores, add WiFi devboard docs * TEMP: generate dev docs * TEMP: generate 0.89.0 docs * Disabling PR trigger * Enable submodules and test build * Enable test build * Disable test build * Change docs directory structure * Fix accidentally committed submodule * Fix submodules * Update links to the developer documentation * Markdown linting * Update workflow, enable test build * Fix doxygen dir path * Update Doxyfile-awesome.cfg * Change paths * Fix upload docs path * Disable pull_request debug trigger * Disable tags building * Remove autolinks and namespaces * Establish basic documentation structure * Add missing changes * Improve stylesheet, move some files * Improve examples * Improve the main page * Improve application dev docs * Improve system programming docs * Improve development tools docs * Improve other docs * Improve application examples * Fix formatting * Fix PVS-studio warnings * Improve visuals * Fix doxygen syntax warnings * Fix broken links * Update doxygen action Co-authored-by: DrunkBatya <[email protected]> Co-authored-by: あく <[email protected]> Co-authored-by: Georgii Surkov <[email protected]> Co-authored-by: Georgii Surkov <[email protected]>
Next-Flip · Mar 6, 2024 · ecab4d5 · ecab4d5
1 parent 5e47048
commit ecab4d5
Show file tree

Hide file tree

Showing 89 changed files with 1,208 additions and 254 deletions.
diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
@@ -0,0 +1,56 @@
+name: 'Generate documentation with Doxygen'
+
+on:
+  push:
+    branches:
+      - dev
+
+env:
+  TARGETS: f7
+  DEFAULT_TARGET: f7
+
+jobs:
+  doxygen:
+    if: ${{ !github.event.pull_request.head.repo.fork }}
+    runs-on: ubuntu-latest
+    steps:
+      - name: 'Wipe workspace'
+        run: find ./ -mount -maxdepth 1 -exec rm -rf {} \;
+
+      - name: 'Checkout code'
+        uses: actions/checkout@v4
+        with:
+          submodules: true
+          fetch-depth: 1
+          ref: ${{ github.event.pull_request.head.sha }}
+
+      - name: 'Get commit details'
+        id: names
+        run: |
+          if [[ ${{ github.event_name }} == 'pull_request' ]]; then
+            TYPE="pull"
+          elif [[ "${{ github.ref }}" == "refs/tags/"* ]]; then
+            TYPE="tag"
+          else
+            TYPE="other"
+          fi
+          python3 scripts/get_env.py "--event_file=${{ github.event_path }}" "--type=$TYPE"
+
+      - name: 'Generate documentation'
+        uses: mattnotmitt/[email protected]
+        with:
+          working-directory: 'documentation/'
+          doxyfile-path: './doxygen/Doxyfile-awesome.cfg'
+
+      - name: 'Upload documentation'
+        uses: jakejarvis/[email protected]
+        env:
+          AWS_S3_BUCKET: "${{ secrets.FW_DOCS_AWS_BUCKET }}"
+          AWS_ACCESS_KEY_ID: "${{ secrets.FW_DOCS_AWS_ACCESS_KEY }}"
+          AWS_SECRET_ACCESS_KEY: "${{ secrets.FW_DOCS_AWS_SECRET_KEY }}"
+          AWS_REGION: "${{ secrets.FW_DOCS_AWS_REGION }}"
+          SOURCE_DIR: "./documentation/doxygen/build/html"
+          DEST_DIR: "${{steps.names.outputs.branch_name}}"
+        with:
+          args: "--delete"
+
diff --git a/.gitmodules b/.gitmodules
@@ -37,4 +37,7 @@
 	url = https://github.com/STMicroelectronics/stm32wbxx_hal_driver
 [submodule "lib/stm32wb_copro"]
 	path = lib/stm32wb_copro
-	url = https://github.com/flipperdevices/stm32wb_copro.git
+    url = https://github.com/flipperdevices/stm32wb_copro.git
+[submodule "documentation/doxygen/doxygen-awesome-css"]
+	path = documentation/doxygen/doxygen-awesome-css
+	url = https://github.com/jothepro/doxygen-awesome-css.git
diff --git a/.vscode/ReadMe.md b/.vscode/ReadMe.md
@@ -1,4 +1,4 @@
-# Visual Studio Code workspace for Flipper Zero
+# Visual Studio Code workspace for Flipper Zero {#vscode}
 
 ## Setup
 

diff --git a/ReadMe.md b/ReadMe.md
@@ -11,14 +11,15 @@
 - [Flipper Zero Official Website](https://flipperzero.one). A simple way to explain to your friends what Flipper Zero can do.
 - [Flipper Zero Firmware Update](https://update.flipperzero.one). Improvements for your dolphin: latest firmware releases, upgrade tools for PC and mobile devices.
 - [User Documentation](https://docs.flipperzero.one). Learn more about your dolphin: specs, usage guides, and anything you want to ask.
+- [Developer Documentation](https://developer.flipper.net/flipperzero/doxygen). Dive into the Flipper Zero Firmware source code: build system, firmware structure, and more.
 
 # Contributing
 
 Our main goal is to build a healthy and sustainable community around Flipper, so we're open to any new ideas and contributions. We also have some rules and taboos here, so please read this page and our [Code of Conduct](/CODE_OF_CONDUCT.md) carefully.
 
 ## I need help
 
-The best place to search for answers is our [User Documentation](https://docs.flipperzero.one). If you can't find the answer there, check our [Discord Server](https://flipp.dev/discord) or our [Forum](https://forum.flipperzero.one/).
+The best place to search for answers is our [User Documentation](https://docs.flipperzero.one). If you can't find the answer there, check our [Discord Server](https://flipp.dev/discord) or our [Forum](https://forum.flipperzero.one/). If you want to contribute to the firmware development, or modify it for your own needs, you can also check our [Developer Documentation](https://developer.flipper.net/flipperzero/doxygen).
 
 ## I want to report an issue
 
@@ -95,7 +96,8 @@ Make sure your Flipper is on, and your firmware is functioning. Connect your Fli
 - [Hardware combos and Un-bricking](/documentation/KeyCombo.md) - recovering your Flipper from the most nasty situations
 - [Flipper File Formats](/documentation/file_formats) - everything about how Flipper stores your data and how you can work with it
 - [Universal Remotes](/documentation/UniversalRemotes.md) - contributing your infrared remote to the universal remote database
-- And much more in the [documentation](/documentation) folder
+- [Firmware Roadmap](/documentation/RoadMap.md)
+- And much more in the [Developer Documentation](https://developer.flipper.net/flipperzero/doxygen)
 
 # Project structure
 

diff --git a/applications/drivers/subghz/cc1101_ext/cc1101_ext.h b/applications/drivers/subghz/cc1101_ext/cc1101_ext.h
@@ -1,6 +1,6 @@
 /**
- * @file furi_hal_subghz.h
- * SubGhz HAL API
+ * @file cc1101_ext.h
+ * @brief External CC1101 transceiver access API.
  */
 
 #pragma once

diff --git a/applications/examples/example_apps_assets/README.md b/applications/examples/example_apps_assets/README.md
@@ -1,7 +1,11 @@
-# Apps Assets folder Example
+# Apps Assets folder Example {#example_app_assets}
 
 This example shows how to use the Apps Assets folder to store data that is not part of the application itself, but is required for its operation, and that data is provided with the application.
 
+## Source code
+
+Source code for this example can be found [here](https://github.com/flipperdevices/flipperzero-firmware/tree/dev/applications/examples/example_apps_assets).
+
 ## What is the Apps Assets Folder?
 
 The **Apps Assets** folder is a folder where external applications unpack their assets.

diff --git a/applications/examples/example_apps_assets/example_apps_assets.c b/applications/examples/example_apps_assets/example_apps_assets.c
@@ -1,3 +1,7 @@
+/**
+ * @file example_apps_assets.c
+ * @brief Application assets example.
+ */
 #include <furi.h>
 #include <storage/storage.h>
 #include <toolbox/stream/stream.h>

diff --git a/applications/examples/example_apps_data/README.md b/applications/examples/example_apps_data/README.md
@@ -1,7 +1,11 @@
-# Apps Data folder Example
+# Apps Data folder Example {#example_app_data}
 
 This example demonstrates how to utilize the Apps Data folder to store data that is not part of the app itself, such as user data, configuration files, and so forth.
 
+## Source code
+
+Source code for this example can be found [here](https://github.com/flipperdevices/flipperzero-firmware/tree/dev/applications/examples/example_apps_data).
+
 ## What is the Apps Data Folder?
 
 The **Apps Data** folder is a folder used to store data for external apps that are not part of the main firmware. 

diff --git a/applications/examples/example_apps_data/example_apps_data.c b/applications/examples/example_apps_data/example_apps_data.c
@@ -1,3 +1,7 @@
+/**
+ * @file example_apps_data.c
+ * @brief Application data example.
+ */
 #include <furi.h>
 #include <storage/storage.h>
 

diff --git a/applications/examples/example_ble_beacon/ble_beacon_app.h b/applications/examples/example_ble_beacon/ble_beacon_app.h
@@ -1,3 +1,7 @@
+/**
+ * @file ble_beacon_app.h
+ * @brief BLE beacon example.
+ */
 #pragma once
 
 #include "extra_beacon.h"

diff --git a/applications/examples/example_custom_font/example_custom_font.c b/applications/examples/example_custom_font/example_custom_font.c
@@ -1,3 +1,7 @@
+/**
+ * @file example_custom_font.c
+ * @brief Custom font example.
+ */
 #include <furi.h>
 #include <furi_hal.h>
 

diff --git a/applications/examples/example_images/ReadMe.md b/applications/examples/example_images/ReadMe.md
@@ -1,11 +1,21 @@
-# Application icons
+# Application icons {#example_app_images}
+
+## Source code
+
+Source code for this example can be found [here](https://github.com/flipperdevices/flipperzero-firmware/tree/dev/applications/examples/example_images).
+
+## General principle
+
 To use icons, do the following:
-* add a line to the application manifest: `fap_icon_assets="folder"`, where `folder` points to the folder where your icons are located
-* add `#include "application_id_icons.h"` to the application code, where `application_id` is the appid from the manifest
-* every icon in the folder will be available as a `I_icon_name` variable, where `icon_name` is the name of the icon file without the extension
+
+* Add a line to the application manifest: `fap_icon_assets="folder"`, where `folder` points to the folder where your icons are located
+* Add `#include "application_id_icons.h"` to the application code, where `application_id` is the appid from the manifest
+* Every icon in the folder will be available as a `I_icon_name` variable, where `icon_name` is the name of the icon file without the extension
 
 ## Example
+
 We have an application with the following manifest:
+
 ```
 App(
     appid="example_images",
@@ -17,6 +27,7 @@ App(
 So the icons are in the `images` folder and will be available in the generated `example_images_icons.h` file.
 
 The example code is located in `example_images_main.c` and contains the following line:
+
 ```
 #include "example_images_icons.h"
 ```

diff --git a/applications/examples/example_images/example_images.c b/applications/examples/example_images/example_images.c
@@ -1,3 +1,7 @@
+/**
+ * @file example_images.c
+ * @brief Custom images example.
+ */
 #include <furi.h>
 #include <furi_hal.h>
 

diff --git a/applications/examples/example_plugins/example_plugins.c b/applications/examples/example_plugins/example_plugins.c
@@ -1,5 +1,7 @@
-/* 
- * An example of a plugin host application.
+/**
+ * @file example_plugins.c
+ * @brief Plugin host application example.
+ *
  * Loads a single plugin and calls its methods.
  */
 

diff --git a/applications/examples/example_plugins/example_plugins_multi.c b/applications/examples/example_plugins/example_plugins_multi.c
@@ -1,5 +1,7 @@
-/*
- * An example of an advanced plugin host application.
+/**
+ * @file example_plugins_multi.c
+ * @brief Advanced plugin host application example.
+ *
  * It uses PluginManager to load all plugins from a directory
  */
 

diff --git a/applications/examples/example_plugins/plugin1.c b/applications/examples/example_plugins/plugin1.c
@@ -1,4 +1,9 @@
-/* A simple plugin implementing example_plugins application's plugin interface */
+/**
+ * @file plugin1.c
+ * @brief Plugin example 1.
+ *
+ * A simple plugin implementing example_plugins application's plugin interface
+ */
 
 #include "plugin_interface.h"
 

diff --git a/applications/examples/example_plugins/plugin2.c b/applications/examples/example_plugins/plugin2.c
@@ -1,4 +1,9 @@
-/* Second plugin implementing example_plugins application's plugin interface */
+/**
+ * @file plugin2.c
+ * @brief Plugin example 2.
+ *
+ * Second plugin implementing example_plugins application's plugin interface
+ */
 
 #include "plugin_interface.h"
 

diff --git a/applications/examples/example_plugins/plugin_interface.h b/applications/examples/example_plugins/plugin_interface.h
@@ -1,7 +1,11 @@
+/**
+ * @file plugin_interface.h
+ * @brief Example plugin interface.
+ *
+ * Common interface between a plugin and host application
+ */
 #pragma once
 
-/* Common interface between a plugin and host application */
-
 #define PLUGIN_APP_ID "example_plugins"
 #define PLUGIN_API_VERSION 1
 

diff --git a/applications/examples/example_plugins_advanced/app_api.h b/applications/examples/example_plugins_advanced/app_api.h
@@ -1,9 +1,12 @@
-#pragma once
-
-/* 
+/**
+ * @file app_api.h
+ * @brief Application API example.
+ *
  * This file contains an API that is internally implemented by the application
  * It is also exposed to plugins to allow them to use the application's API.
  */
+#pragma once
+
 #include <stdint.h>
 
 #ifdef __cplusplus

diff --git a/applications/examples/example_plugins_advanced/plugin1.c b/applications/examples/example_plugins_advanced/plugin1.c
@@ -1,4 +1,7 @@
-/*
+/**
+ * @file plugin1.c
+ * @brief Plugin example 1.
+ *
  * This plugin uses both firmware's API interface and private application headers.
  * It can be loaded by a plugin manager that uses CompoundApiInterface,
  * which combines both interfaces.

diff --git a/applications/examples/example_plugins_advanced/plugin2.c b/applications/examples/example_plugins_advanced/plugin2.c
@@ -1,4 +1,7 @@
-/*
+/**
+ * @file plugin2.c
+ * @brief Plugin example 2.
+ *
  * This plugin uses both firmware's API interface and private application headers.
  * It can be loaded by a plugin manager that uses CompoundApiInterface,
  * which combines both interfaces.

diff --git a/applications/examples/example_plugins_advanced/plugin_interface.h b/applications/examples/example_plugins_advanced/plugin_interface.h
@@ -1,7 +1,11 @@
+/**
+ * @file plugin_interface.h
+ * @brief Example plugin interface.
+ *
+ * Common interface between a plugin and host application
+ */
 #pragma once
 
-/* Common interface between a plugin and host application */
-
 #define PLUGIN_APP_ID "example_plugins_advanced"
 #define PLUGIN_API_VERSION 1
 

diff --git a/applications/examples/example_thermo/README.md b/applications/examples/example_thermo/README.md
@@ -1,8 +1,14 @@
-# 1-Wire Thermometer
+# 1-Wire Thermometer {#example_thermo}
+
 This example application demonstrates the use of the 1-Wire library with a DS18B20 thermometer. 
 It also covers basic GUI, input handling, threads and localisation.
 
+## Source code
+
+Source code for this example can be found [here](https://github.com/flipperdevices/flipperzero-firmware/tree/dev/applications/examples/example_thermo).
+
 ## Electrical connections
+
 Before launching the application, connect the sensor to Flipper's external GPIO according to the table below:
 | DS18B20 | Flipper |
 | :-----: | :-----: |
@@ -15,12 +21,14 @@ Before launching the application, connect the sensor to Flipper's external GPIO
 *NOTE 2*: For any other pin than 17, connect an external 4.7k pull-up resistor to pin 9.
 
 ## Launching the application
+
 In order to launch this demo, follow the steps below:
 1. Make sure your Flipper has an SD card installed.
 2. Connect your Flipper to the computer via a USB cable.
 3. Run `./fbt launch APPSRC=example_thermo` in your terminal emulator of choice.
 
 ## Changing the data pin
+
 It is possible to use other GPIO pin as a 1-Wire data pin. In order to change it, set the `THERMO_GPIO_PIN` macro to any of the options listed below:
 
 ```c

diff --git a/applications/examples/example_thermo/example_thermo.c b/applications/examples/example_thermo/example_thermo.c
@@ -1,4 +1,7 @@
-/*
+/**
+ * @file example_thermo.c
+ * @brief 1-Wire thermometer example.
+ *
  * This file contains an example application that reads and displays
  * the temperature from a DS18B20 1-wire thermometer.
  *

diff --git a/applications/services/gui/canvas.h b/applications/services/gui/canvas.h
@@ -239,7 +239,6 @@ void canvas_draw_bitmap(
  * @param      x        x coordinate
  * @param      y        y coordinate
  * @param      icon     Icon instance
- * @param      flip     IconFlip
  * @param      rotation IconRotation
  */
 void canvas_draw_icon_ex(

diff --git a/applications/services/gui/canvas_i.h b/applications/services/gui/canvas_i.h
@@ -107,7 +107,7 @@ CanvasOrientation canvas_get_orientation(const Canvas* canvas);
 
 /** Draw a u8g2 bitmap
  *
- * @param      canvas   Canvas instance
+ * @param      u8g2     u8g2 instance
  * @param      x        x coordinate
  * @param      y        y coordinate
  * @param      width    width

diff --git a/applications/services/gui/elements.h b/applications/services/gui/elements.h
@@ -188,8 +188,7 @@ void elements_bubble(Canvas* canvas, uint8_t x, uint8_t y, uint8_t width, uint8_
  * @param   canvas      Canvas instance
  * @param   x           left x coordinates
  * @param   y           top y coordinate
- * @param   width       bubble width
- * @param   height      bubble height
+ * @param   text        text to display
  * @param   horizontal  horizontal aligning
  * @param   vertical    aligning
  */

diff --git a/applications/services/gui/modules/dialog_ex.h b/applications/services/gui/modules/dialog_ex.h
@@ -114,7 +114,6 @@ void dialog_ex_set_text(
  * @param      x          x position
  * @param      y          y position
  * @param      icon       The icon
- * @param      name  icon to be shown
  */
 void dialog_ex_set_icon(DialogEx* dialog_ex, uint8_t x, uint8_t y, const Icon* icon);
 

diff --git a/applications/services/gui/scene_manager.h b/applications/services/gui/scene_manager.h
@@ -108,7 +108,6 @@ bool scene_manager_handle_back_event(SceneManager* scene_manager);
  * Calls Scene event handler with Tick event parameter
  *
  * @param      scene_manager  SceneManager instance
- * @return     true if event was consumed, false otherwise
  */
 void scene_manager_handle_tick_event(SceneManager* scene_manager);