Merge pull request #1113 from tier4/feature/doxygen

Feature/doxygen

.github/workflows/Documentation.yaml

@@ -30,81 +30,6 @@ jobs:
           poetry-version: "1.5.1"
       - name: install
         run: poetry install --no-interaction
-      - name: Install doxygen/depends of doxybook
-        run: sudo apt install -y doxygen wget
-      - name: Wget package
-        run: |
-          wget https://github.com/matusnovak/doxybook2/releases/download/v1.2.3/doxybook2-linux-amd64-v1.2.3.zip
-          mkdir -p ~/doxybook2
-          cp -rf . ~/doxybook2
-          cd ~/doxybook2
-          unzip doxybook2-linux-amd64-v1.2.3.zip
-      # generating traffic_simulator package documentation
-      - name: Generate doxygen for traffic_simulator package
-        run: |
-          cd docs/package/traffic_simulator
-          doxygen Doxyfile
-      - name: Generate markdown for traffic_simulator package
-        run: |
-          export PATH="$PATH:~/doxybook2/bin"
-          cd docs/package/traffic_simulator
-          mkdir -p ./markdown/Classes
-          doxybook2 --input ./build/ --output ./markdown -c config.json
-      # generating simple_sensor_simulator package documentation
-      - name: Generate doxygen for simple_sensor_simulator package
-        run: |
-          cd docs/package/simple_sensor_simulator
-          doxygen Doxyfile
-      - name: Generate markdown for simple_sensor_simulator package
-        run: |
-          export PATH="$PATH:~/doxybook2/bin"
-          cd docs/package/simple_sensor_simulator
-          mkdir -p ./markdown/Classes
-          doxybook2 --input ./build/ --output ./markdown -c config.json
-      # generating simulation_interface package documentation
-      - name: Generate doxygen for simulation_interface package
-        run: |
-          cd docs/package/simulation_interface
-          doxygen Doxyfile
-      - name: Generate markdown for simulation_interface package
-        run: |
-          export PATH="$PATH:~/doxybook2/bin"
-          cd docs/package/simulation_interface
-          mkdir -p ./markdown/Classes
-          doxybook2 --input ./build/ --output ./markdown -c config.json
-      # generating openscenario_interpreter package documentation
-      - name: Generate doxygen for openscenario_interpreter package
-        run: |
-          cd docs/package/openscenario_interpreter
-          doxygen Doxyfile
-      - name: Generate markdown for openscenario_interpreter package
-        run: |
-          export PATH="$PATH:~/doxybook2/bin"
-          cd docs/package/openscenario_interpreter
-          mkdir -p ./markdown/Classes
-          doxybook2 --input ./build/ --output ./markdown -c config.json
-      # generating openscenario_visualization package documentation
-      - name: Generate doxygen for openscenario_visualization package
-        run: |
-          cd docs/package/openscenario_visualization
-          doxygen Doxyfile
-      - name: Generate markdown for openscenario_visualization package
-        run: |
-          export PATH="$PATH:~/doxybook2/bin"
-          cd docs/package/openscenario_visualization
-          mkdir -p ./markdown/Classes
-          doxybook2 --input ./build/ --output ./markdown -c config.json
-      # generating geometry package documentation
-      - name: Generate doxygen for geometry package
-        run: |
-          cd docs/package/geometry
-          doxygen Doxyfile
-      - name: Generate markdown for geometry package
-        run: |
-          export PATH="$PATH:~/doxybook2/bin"
-          cd docs/package/geometry
-          mkdir -p ./markdown/Classes
-          doxybook2 --input ./build/ --output ./markdown -c config.json
       - name: Generate documentation
         run: poetry run mkdocs build
       - name: Upload Artifact
@@ -121,3 +46,26 @@ jobs:
           publish_dir: site
           keep_files: false
           external_repository: tier4/scenario_simulator_v2-docs
+  generate_api_document: 
+    name: Generate API documentation
+    runs-on: ubuntu-22.04
+    steps:
+      - uses: actions/checkout@v2-beta
+      - name: Install doxygen
+        run: sudo apt install -y doxygen
+      - name: Build document
+        run: doxygen Doxyfile
+      - name: Upload Artifact
+        uses: actions/upload-artifact@v2
+        with:
+          name: api_documentation_site
+          path: html
+          retention-days: 1
+      - name: Publish Documentation
+        if: ${{ github.event_name == 'push' || github.event_name == 'schedule' || github.event_name == 'workflow_dispatch'}}
+        uses: peaceiris/actions-gh-pages@v3
+        with:
+          personal_token: ${{ secrets.BLOOM_GITHUB_TOKEN }}
+          publish_dir: html
+          keep_files: false
+          external_repository: tier4/scenario_simulator_v2-api-docs

.gitignore

@@ -6,6 +6,7 @@
 
 # log file
 *.log
+log
 
 # files too large
 *.pcd
@@ -20,3 +21,4 @@ latex
 scenario_simulator.tar
 site
 *.pyc
+build

Doxyfile

@@ -0,0 +1,107 @@
+PROJECT_NAME = scenario_simulator_v2 C++ API
+
+DOXYFILE_ENCODING = UTF-8
+
+ENABLE_PREPROCESSING   = YES
+EXPAND_ONLY_PREDEF     = YES
+EXTRACT_ALL            = YES
+EXTRACT_ANON_NSPACES   = YES
+EXTRACT_LOCAL_CLASSES  = YES
+EXTRACT_LOCAL_METHODS  = YES
+GENERATE_HTML          = YES
+GENERATE_LATEX         = NO
+GENERATE_XML           = NO
+
+INPUT                  += README.md
+
+INPUT                  += common/math/geometry
+INPUT                  += common/math/arithmetic
+INPUT                  += common/scenario_simulator_exception
+INPUT                  += common/simple_junit
+INPUT                  += common/status_monitor
+INPUT                  += external/concealer
+INPUT                  += mock/cpp_mock_scenarios
+INPUT                  += simulation/behavior_tree_plugin
+INPUT                  += simulation/do_nothing_plugin
+INPUT                  += simulation/simple_sensor_simulator
+INPUT                  += simulation/simulation_interface
+INPUT                  += simulation/traffic_simulator
+INPUT                  += openscenario/openscenario_interpreter
+INPUT                  += openscenario/openscenario_interpreter_example
+INPUT                  += openscenario/openscenario_preprocessor
+INPUT                  += openscenario/openscenario_visualization
+
+IMAGE_PATH             += common/math/geometry
+IMAGE_PATH             += common/math/arithmetic
+IMAGE_PATH             += common/scenario_simulator_exception
+IMAGE_PATH             += common/simple_junit
+IMAGE_PATH             += common/status_monitor
+IMAGE_PATH             += external/concealer
+IMAGE_PATH             += mock/cpp_mock_scenarios
+IMAGE_PATH             += simulation/behavior_tree_plugin
+IMAGE_PATH             += simulation/do_nothing_plugin
+IMAGE_PATH             += simulation/simple_sensor_simulator
+IMAGE_PATH             += simulation/simulation_interface
+IMAGE_PATH             += simulation/traffic_simulator
+IMAGE_PATH             += openscenario/openscenario_interpreter
+IMAGE_PATH             += openscenario/openscenario_interpreter_example
+IMAGE_PATH             += openscenario/openscenario_preprocessor
+IMAGE_PATH             += openscenario/openscenario_visualization
+
+EXAMPLE_PATH           += common/math/geometry
+EXAMPLE_PATH           += common/scenario_simulator_exception
+EXAMPLE_PATH           += common/math/arithmetic
+EXAMPLE_PATH           += common/simple_junit
+EXAMPLE_PATH           += common/status_monitor
+EXAMPLE_PATH           += external/concealer
+EXAMPLE_PATH           += mock/cpp_mock_scenarios
+EXAMPLE_PATH           += simulation/behavior_tree_plugin
+EXAMPLE_PATH           += simulation/do_nothing_plugin
+EXAMPLE_PATH           += simulation/simple_sensor_simulator
+EXAMPLE_PATH           += simulation/simulation_interface
+EXAMPLE_PATH           += simulation/traffic_simulator
+EXAMPLE_PATH           += openscenario/openscenario_interpreter
+EXAMPLE_PATH           += openscenario/openscenario_interpreter_example
+EXAMPLE_PATH           += openscenario/openscenario_preprocessor
+EXAMPLE_PATH           += openscenario/openscenario_visualization
+
+INPUT_ENCODING         = UTF-8
+MACRO_EXPANSION        = YES
+OUTPUT_DIRECTORY       = 
+OUTPUT_LANGUAGE        = English
+RECURSIVE              = YES
+SKIP_FUNCTION_MACROS   = NO
+XML_OUTPUT             = build
+
+FILE_PATTERNS += *.hpp
+FILE_PATTERNS += *.cpp
+FILE_PATTERNS += *.md
+
+EXPAND_AS_DEFINED += BOILERPLATE
+EXPAND_AS_DEFINED += CASE
+EXPAND_AS_DEFINED += DEFINE_CHECK_FUNCTION
+EXPAND_AS_DEFINED += DEFINE_ERROR_CATEGORY
+EXPAND_AS_DEFINED += DEFINE_GETTER
+EXPAND_AS_DEFINED += DEFINE_GETTER_SETTER
+EXPAND_AS_DEFINED += DEFINE_LAZY_VISITOR
+EXPAND_AS_DEFINED += DEFINE_STATIC_DATA_MEMBER_DETECTOR
+EXPAND_AS_DEFINED += EMPLACE
+EXPAND_AS_DEFINED += EXPECT_ACCEL_EQ
+EXPAND_AS_DEFINED += EXPECT_ACTION_STATUS_EQ
+EXPAND_AS_DEFINED += EXPECT_DECIMAL_EQ
+EXPAND_AS_DEFINED += EXPECT_DETECTION_SENSOR_CONFIGURATION_EQ
+EXPAND_AS_DEFINED += EXPECT_LANELET_POSE_EQ
+EXPAND_AS_DEFINED += EXPECT_POINT_EQ
+EXPAND_AS_DEFINED += EXPECT_POSE_EQ
+EXPAND_AS_DEFINED += EXPECT_QUATERNION_EQ
+EXPAND_AS_DEFINED += EXPECT_TWIST_EQ
+EXPAND_AS_DEFINED += EXPECT_VECTOR3_EQ
+EXPAND_AS_DEFINED += FORWARD_GETTER_TO_TRAFFIC_LIGHT_MANAGER
+EXPAND_AS_DEFINED += FORWARD_TO_ENTITY
+EXPAND_AS_DEFINED += FORWARD_TO_ENTITY_MANAGER
+EXPAND_AS_DEFINED += FORWARD_TO_HDMAP_UTILS
+EXPAND_AS_DEFINED += TEST
+EXPAND_AS_DEFINED += THROW_ERROR
+EXPAND_AS_DEFINED += THROW_SEMANTIC_ERROR
+EXPAND_AS_DEFINED += THROW_SIMULATION_ERROR
+EXPAND_AS_DEFINED += THROW_SYNTAX_ERROR

README.md

@@ -1,4 +1,4 @@
-# scenario_simulator_v2
+# scenario_simulator_v2 {#mainpage}
 
 Scenario testing framework for Autoware.
 
@@ -9,4 +9,5 @@ Scenario testing framework for Autoware.
 
 ## Documentation
 
-See [GitHub Pages](https://tier4.github.io/scenario_simulator_v2-docs/)
+See [Documentation](https://tier4.github.io/scenario_simulator_v2-docs/)
+See [C++ API Documentation](https://tier4.github.io/scenario_simulator_v2-api-docs/index.html)

common/scenario_simulator_exception/include/scenario_simulator_exception/exception.hpp

@@ -37,21 +37,19 @@ struct Error : public std::runtime_error
     using Error::Error;                 \
   }
 
-// Autoware encountered some problem that led to a simulation failure.
+/// @brief Autoware encountered some problem that led to a simulation failure.
 DEFINE_ERROR_CATEGORY(AutowareError);
 
-// Although there were no syntactic errors in the description of the scenario,
-// differences in meaning and inconsistencies were found.
+/// @brief Although there were no syntactic errors in the description of the scenario, differences in meaning and inconsistencies were found.
 DEFINE_ERROR_CATEGORY(SemanticError);
 
-// A problem occurred that interfered with the continuation of the simulation.
+/// @brief A problem occurred that interfered with the continuation of the simulation.
 DEFINE_ERROR_CATEGORY(SimulationError);
 
-// Metric module detects specification violation in simulation.
+/// @brief When simulator detects specification violation in simulation.
 DEFINE_ERROR_CATEGORY(SpecificationViolation);
 
-// There is a syntactic error in the description of the scenario. Or you are
-// using a feature that is not yet supported by our implementation.
+/// @brief  There is a syntactic error in the description of the scenario. Or you are using a feature that is not yet supported by our implementation.
 DEFINE_ERROR_CATEGORY(SyntaxError);
 
 #undef DEFINE_ERROR_CATEGORY
@@ -62,9 +60,6 @@ DEFINE_ERROR_CATEGORY(SyntaxError);
 #define THROW_SIMULATION_ERROR(...) /*  */ THROW_ERROR(common::SimulationError, __VA_ARGS__)
 #define THROW_SPECIFICATION_VIOLATION(...) THROW_ERROR(common::SpecificationViolation, __VA_ARGS__)
 #define THROW_SYNTAX_ERROR(...) /*      */ THROW_ERROR(common::SyntaxError, __VA_ARGS__)
-
-#define SPECIFICATION_VIOLATION(...) \
-  common::SpecificationViolation(__FILE__, ":", __LINE__, ": ", __VA_ARGS__)
 }  // namespace scenario_simulator_exception
 }  // namespace common
 

common/simple_junit/include/simple_junit/junit5.hpp

@@ -123,7 +123,7 @@ struct Error
 
 struct Properties
 {
-  // TODO
+  /// @todo implement `properties` in junit.
 };
 
 /*
@@ -137,7 +137,7 @@ struct Properties
 
 struct Property
 {
-  // TODO
+  /// @todo implement `property` in junit.
 };
 
 /*
@@ -225,7 +225,7 @@ struct SimpleTestCase
       current_node.append_attribute("status") = testcase.status.c_str();
     }
 
-    // TODO skipped
+    /// @todo implement `skipped` element in junit.
 
     for (const auto & each : testcase.error) {
       current_node.append_child("error") << each;
@@ -235,9 +235,9 @@ struct SimpleTestCase
       current_node.append_child("failure") << each;
     }
 
-    // TODO system-out
+    /// @todo implement `system-out` element in junit.
 
-    // TODO system-err
+    /// @todo implement `system-err` element in junit.
 
     return node;
   }

docs/developer_guide/About.md

@@ -6,6 +6,8 @@ This documentation describes the architecture design of this scenario testing fr
 
 This framework is designed for executing scenario tests with Autoware.
 
+C++ API documentation of scenario_simulator_v2 can be seen [here](https://tier4.github.io/scenario_simulator_v2-api-docs/index.html).
+
 <font color="#065479E">**This framework is designed to easily accommodate multiple simulators and scenario description formats.**</font>
 
 ## Simple sensor simulator