Update documentation

- Update HTML documentation.
- Automatic tagging from Github workflow.

Author: dmg0345

.clang-tidy

@@ -17,6 +17,7 @@ Checks: >
   -cppcoreguidelines-interfaces-global-init,
   -cppcoreguidelines-avoid-magic-numbers,
   -cppcoreguidelines-avoid-goto,
+  -cppcoreguidelines-macro-usage,
   misc-*,
   -misc-non-private-member-variables-in-classes,
   portability-*,

.github/workflows/reusable-full.yml

@@ -78,6 +78,49 @@ jobs:
           ref: ${{ github.sha }}
           path: ${{ env.CLONE_FOLDER }}
           submodules: recursive
+      - name: Tag commit on production
+        run: |
+          # Enter folder with repository.
+          Push-Location "$($ENV:CLONE_FOLDER)";
+
+          # Get current version from configuration file.
+          $confFile = Get-Content "./doc/conf.py" -Encoding utf8 -Raw;
+          $confMatch = $confFile -Match 'version[\s]*=[\s]*"([0-9]+\.[0-9]+\.[0-9]+)"[\s]*';
+          if ($confMatch -eq $false) { throw "Unable to retrieve version from configuration file..."; }
+          $currVersion = $Matches[1];
+
+          # Attempt to tag only on 'production' kind of deployments.
+          if ('${{ inputs.deploy }}' -eq "production")
+          {
+            # Fetch all tags from remote.
+            git fetch --tags --force;
+            if ($LastExitCode -ne 0) { throw "Unable to fetch tags from repository."; }
+
+            # Check if current commit is already tagged, in which case skip it.
+            $out = git tag -l -n0 --points-at "${{ github.sha }}";
+            if ($LastExitCode -ne 0) { throw "Unable to determine if current commit is tagged."; }
+            if ($out.Length -eq 0)
+            {
+                $out = git tag -l -n0 "$currVersion";
+                if ($LastExitCode -ne 0) { throw "Unable to determine if tag exists for version."; }
+                if ($out.Length -ne 0) { throw "Version '$out' is already tagged."; }
+
+                # Create tag locally for documentation and other purposes, do not push, would need perms.
+                git tag "$currVersion" "${{ github.sha }}";
+                if ($LastExitCode -ne 0) { throw "Unable to create tag '$currVersion' for '${{ github.sha }}'"; }
+            }
+            else
+            {
+              Write-Host "Commit '${{ github.sha }}' is already tagged...";
+            }
+          }
+          else
+          {
+            Write-Host "No tagging necessary for '${{ inputs.deploy }}' deployment...";
+          }
+
+          # Return to original folder.
+          Pop-Location;
       - name: Build every target with CMake
         run: |
           # Enter Python virtual environment.
@@ -115,7 +158,6 @@ jobs:
             tar `
               --exclude="*.obj" `
               --exclude="*.o" `
-              --exclude="*.pdf" `
               --exclude="$($cfg.Name)/.git" `
               -cf "$($cfg.Name).repo.tar.gz" "$($cfg.Name)";
             if ($LastExitCode -ne 0) { throw "$($cfg.Name): Compressing the repository failed with error '$LastExitCode'." }

.vscode/settings.json

@@ -25,6 +25,8 @@
     },
     // Do not reveal files in the explorer as they are open.
     "explorer.autoReveal": false,
+    // Disable sticky scroll.
+    "editor.stickyScroll.enabled": false,
     // Default theme.
     "workbench.colorTheme": "Visual Studio Dark - C++",
     // Increase line buffer of the integrated terminal.

doc/app/client.rst

@@ -0,0 +1,7 @@
+Client
+========================================================================================================================
+
+.. doxygennamespace:: App::Client
+    :desc-only:
+
+.. doxygenfunction:: App::Client::main

doc/app/index.rst

@@ -0,0 +1,13 @@
+Application
+========================================================================================================================
+
+.. doxygennamespace:: App
+    :desc-only:
+
+.. toctree::
+    :titlesonly:
+    :hidden:
+
+    client
+    server
+    startup

doc/app/server.rst

@@ -0,0 +1,7 @@
+Server
+========================================================================================================================
+
+.. doxygennamespace:: App::Server
+    :desc-only:
+
+.. doxygenfunction:: App::Server::main

doc/app/startup.rst

@@ -0,0 +1,9 @@
+Startup
+========================================================================================================================
+
+.. doxygennamespace:: App::Startup
+    :desc-only:
+
+.. doxygenfunction:: App::Startup::main
+
+.. doxygenfunction:: main(int argc, char **argv)

doc/conf.py

@@ -17,6 +17,7 @@
 import sphinx
 import subprocess
 import os
+import docutils
 import xml.etree.ElementTree as ET
 
 ## Project information #################################################################################################
@@ -98,6 +99,18 @@
 html_logo = None
 # Path to the HTML fav icon.
 html_favicon = None
+# Paths to static files and folders, will be stored in '_static' folder.
+html_static_path = [
+    "../other/commonapi_docs/FrancaUserGuide-0.12.0.1.pdf",
+    "../other/commonapi_docs/CommonAPICppSpecification.pdf",
+    "../other/commonapi_docs/CommonAPICppUserGuide.pdf",
+    "../other/commonapi_docs/CommonAPI-4_deployment_spec.fdepl",
+    "../other/commonapi_docs/dbus/CommonAPI-4-DBus_deployment_spec.fdepl",
+    "../other/commonapi_docs/dbus/CommonAPIDBusCppUserGuide.pdf",
+    "../other/commonapi_docs/someip/CommonAPI-4-SOMEIP_deployment_spec.fdepl",
+    "../other/commonapi_docs/someip/CommonAPISomeIPCppUserGuide.pdf",
+    "../other/commonapi_docs/someip/vsomeipUserGuide.html"
+]
 # Add permalinks to every section.
 html_permalinks = True
 # Do not include the original sources in the final documentation.
@@ -174,43 +187,55 @@ def breathe_load_tags_on_doxyfile() -> None:
     if len(elems) == 1:
         _ = [tags.add(tag.text) for tag in elems[0] if tag.text.isidentifier()]
 
-def on_missing_reference(_app: sphinx.application.Sphinx,
-                         _env: sphinx.app.builder.env,
+def on_missing_reference(app: sphinx.application.Sphinx,
+                         env: sphinx.environment.BuildEnvironment,
                          node: sphinx.addnodes.pending_xref,
-                         contnode: sphinx.addnodes.pending_xref):
-    """Handler for 'on_missing_reference' warning. Lots of false positives can be raised by Sphinx from this, for
+                         contnode: docutils.nodes.TextElement) -> docutils.nodes.reference | None:
+    """Handler for 'missing-reference' warning. Lots of false positives can be raised by Sphinx from this, for
     example from missing references to standard library types or missing references to third-party types that are not
     documented by Sphinx or which are not processed by Doxygen.
 
-    One solution is to disable errors as warnings, but this is not convenient as it could hide real errors.
+    One solution is to disable errors as warnings, but this is not convenient as it could hide real errors. Another
+    solution implies the use of 'c_extra_keywords' and 'c_id_attributes', however, this also causes other kind of
+    errors. Thus the solution to handle the event directly.
 
-    The implementation of this handler here allows to ignore warnings for the types specified."""
+    The implementation of this handler allows to ignore this kind of warnings and also to look for substitue
+    nodes when a reference has not been found."""
     # Print missing reference in color in the terminal to differentiate it.
-    # print(f"\033[93m mon_missing_reference: {node}.\033[00m")
-
-    # Missing references handler, lots of false positives can occur in the C/C++ domain.
-    # Trying to handle them with 'c_extra_keywords' or 'c_id_attributes' generates other kind of errors.
-    # Allowed reference domains, reference targets and reference types that can be missing are described below.
-    refdomains = ["c", "cpp"]
-    reftypes = ["identifier"]
-    
-    # C Standard library identifiers to ignore.
-    c_std_reftargets = []
-
-    # C++ Standard library identifiers to ignore.
-    cpp_std_reftargets = ["size_t"]
-
-    # Build total reftargets.
-    reftargets = [
-        *c_std_reftargets,
-        *cpp_std_reftargets
-    ]
-
-    # Check if the reference is of C/C++ type and it can be allowed to be missing.
-    if all((node["refdomain"] in refdomains, node["reftarget"] in reftargets, node["reftype"] in reftypes)):
-        # Return OK in Sphinx.
-        return contnode
-    # Raise error in Sphinx.
+    print(f"\033[93m on_missing_reference: {node}.\033[00m")
+
+    # The lookup dictionary with missing targets and replacements.
+    reftargets = {
+        "c": {
+
+        },
+        "cpp": {
+            "*": {
+                "size_t": None, "uint32_t": None,
+                "v0_1": None, "v0_1::commonapi": None, "v0_1::commonapi::app": None, "v0_1::commonapi::app::AppStubDefault": None
+            }
+        }
+    }
+
+    # Obtain the reference target replacement, if any, note that refdoc replacements take priority over global ones.
+    domain_dict = reftargets.get(node["refdomain"], {})
+    reftarget = {**domain_dict.get("*", {}), **domain_dict.get(node["refdoc"], {})}.get(node["reftarget"], False)
+
+    # Check if the replacement target has been found and the node refers to an identifier.
+    if all([node["reftype"] == "identifier", reftarget is not False]):
+        # No explicit replacement for target, thus acknowledge warning and continue with node as is.
+        if reftarget is None:
+            return contnode
+
+        # Find explicit replacement for target, and ensure there is no ambiguity.
+        reftarget_cand = env.domains[node["refdomain"]].resolve_any_xref(
+            env, './index', app.builder, reftarget, node, contnode
+        )
+        if len(reftarget_cand) != 1:
+            raise sphinx.errors.ExtensionError(f"Found {len(reftarget_cand)} '{reftarget}' replacements for '{node['reftarget']}'.")
+        return reftarget_cand[0][1]
+
+    # Could not resolve identifier, let other handlers resolve it if they can.
     return None
 
 def setup(app: sphinx.application.Sphinx):

doc/doxyfile

@@ -291,7 +291,7 @@ ALIASES               +="endrst=@endverbatim"
 # members will be omitted, etc.
 # The default value is: NO.
 
-OPTIMIZE_OUTPUT_FOR_C  = YES
+OPTIMIZE_OUTPUT_FOR_C  = NO
 
 # Set the OPTIMIZE_OUTPUT_JAVA tag to YES if your project consists of Java or
 # Python sources only. Doxygen will then generate output that is more tailored
@@ -660,7 +660,7 @@ INLINE_INFO            = YES
 # name. If set to NO, the members will appear in declaration order.
 # The default value is: YES.
 
-SORT_MEMBER_DOCS       = YES
+SORT_MEMBER_DOCS       = NO
 
 # If the SORT_BRIEF_DOCS tag is set to YES then doxygen will sort the brief
 # descriptions of file, namespace and class members alphabetically by member

doc/index.rst

@@ -1,13 +1,43 @@
 Introduction
 ========================================================================================================================
 
-|ProjectFriendlyName|, version |ProjectVersion|, is a software project.
+|ProjectFriendlyName|, version |ProjectVersion|, is an example integration and playground of a client and server
+architecture using the `COVESA / GENIVI Common API C++ Framework <https://covesa.github.io/capicxx-core-tools/>`_,
+covering both runtimes and code generators and also supporting both
+`D-Bus <https://www.freedesktop.org/wiki/Software/dbus/>`_ and `SOME/IP <https://some-ip.com/>`_ bindings.
 
-.. doxygennamespace:: App
-    :desc-only:
+For convenience, a list of relevant repositories and resources from the relevant organizations is listed below.
+These resources are the latest at the time of writing, and the ones used for the development of this project.
 
-.. doxygennamespace:: Utils
-    :desc-only:
+- `COVESA / GENIVI Common API C++ Core Tools v3.2.15 repository <https://github.com/COVESA/capicxx-core-tools/tree/3.2.15>`_
+
+  - `Common API C++ Core Tools v3.2.15 Specification <_static/CommonAPICppSpecification.pdf>`_
+  - `Common API C++ Core Tools v3.2.15 User Guide <_static/CommonAPICppUserGuide.pdf>`_
+  - `Common API C++ Core Tools v3.2.15 Deployment Specification <_static/CommonAPI-4_deployment_spec.fdepl>`_
+
+- `COVESA / GENIVI Common API C++ D-Bus Tools v3.2.15 repository <https://github.com/COVESA/capicxx-dbus-tools/tree/3.2.15>`_
+
+  - `Common API C++ D-Bus Tools v3.2.15 User Guide <_static/CommonAPIDBusCppUserGuide.pdf>`_
+  - `Common API C++ D-Bus Tools v3.2.15 Deployment Specification <_static/CommonAPI-4-DBus_deployment_spec.fdepl>`_
+
+- `COVESA / GENIVI Common API C++ SOME/IP Tools v3.2.15 repository <https://github.com/COVESA/capicxx-someip-tools/tree/3.2.15>`_
+
+  - `Common API C++ SOME/IP Tools v3.2.15 User Guide <_static/CommonAPISomeIPCppUserGuide.pdf>`_
+  - `Common API C++ SOME/IP Tools v3.2.15 Deployment Specification <_static/CommonAPI-4-SOMEIP_deployment_spec.fdepl>`_
+
+- `COVESA / GENIVI vSomeIP v3.5.3 repository <https://github.com/COVESA/vsomeip/tree/3.5.3>`_
+
+  - `vSomeIP v3.5.3 User Guide <_static/vsomeipUserGuide.html>`_
+
+- `COVESA / GENIVI Common API C++ Core Runtime v3.2.4 repository <https://github.com/COVESA/capicxx-core-runtime/tree/3.2.4>`_
+- `COVESA / GENIVI Common API C++ D-Bus Runtime v3.2.3-r1 repository <https://github.com/COVESA/capicxx-dbus-runtime/tree/3.2.3-r1>`_
+- `COVESA / GENIVI Common API C++ SOME/IP Runtime v3.2.4 repository <https://github.com/COVESA/capicxx-someip-runtime/tree/3.2.4>`_
+- `Franca User Guide v0.12.0.1 <_static/FrancaUserGuide-0.12.0.1.pdf>`_
+
+It is recommended to first refer to the :any:`Application <::App>` to understand the client/server architecture,
+followed by the :any:`Common API C++ Abstraction <Utils::Capi>` to understand the Common API C++ framework integration.
+The :any:`Test Suites <Tests::Suites>` provide some practice examples and a playground for experimentation and testing
+of the different features of the Common API C++ framework.
 
 The source code for |ProjectFriendlyName| is hosted at `Github <https://github.com/dmg0345/commonapi_cpp_examples>`_ and
 related *Docker* images for development containers are located at `DockerHub <https://hub.docker.com/r/dmg00345/commonapi_cpp_examples>`_.
@@ -17,7 +47,15 @@ related *Docker* images for development containers are located at `DockerHub <ht
 .. note::
 
     This is the documentation for |ProjectFriendlyName|, version |ProjectVersion|, refer to
-    :doc:`version/index` for more details regarding the release.
+    :doc:`utils/version` for more details regarding the release.
+
+.. important::
+
+    This project is an open source project built from publicly available repositories and documentation and not
+    affiliated with *COVESA / GENIVI*.
+
+    This project is an example integration of the *Common API C++ Framework* based on previous experience and
+    interpretation of the author of that documentation.
 
 License
 -----------------------------------------------------------------------------------------------------------------------
@@ -30,4 +68,6 @@ License
     :hidden:
 
     self
-    version/index
+    app/index
+    utils/index
+    tests/index