add(doc): Add coding conventions to the sphinx documentation

currently we have the coding conventions mentioned in an PDF format
changes are made as part of this commit to include coding conventions under developer information in the documentation

authored by Raghunandan Netrapalli Madhusudhan (raghunandan.madhusudhan@in-tech.com)

CONTRIBUTING.md

@@ -33,4 +33,17 @@ To build the project, follow the guide in "pathToRepo\sim\doc\OSI World Setup Gu
 
 The branch 'develop' contains the contributions that will be included in the next release. The 'main' branch contains the latest stable release.
 
-A detailed development process can be found [here](https://gitlab.eclipse.org/groups/eclipse/openpass/-/wikis/home).
+### Committer contribution process
+
+1.  (you) Discuss your planned contribution with the project lead first.
+2.  (you) If needed, create the Issue on GitLab and assign it to yourself.
+3.  (you) In GitLab, create a merge request. The related branch will be created from the branch 'develop'.
+4.  (you) Work on it and respect the following points:
+    - Stick to the [coding guideline](doc/source/developer_information/30_coding_conventions.rst)
+    - Amend the documentation if necessary
+    - Provide unit-tests in googletest format
+    - Make sure, the code base with your contribution compiles
+5.	(you) Assign the issue to another committer.
+6.	(other committer) Review the code.
+7.	(other committer) To merge new branch into 'develop' you can close the merge request via GitLab.
+8.	(you) Present your contribution to the openPASS WG

doc/source/developer_information/30_coding_conventions.rst

+..
+  *******************************************************************************
+  Copyright (c) 2023 Bayerische Motoren Werke Aktiengesellschaft (BMW AG)
+
+  This program and the accompanying materials are made available under the
+  terms of the Eclipse Public License 2.0 which is available at
+  http://www.eclipse.org/legal/epl-2.0.
+
+  SPDX-License-Identifier: EPL-2.0
+  *******************************************************************************
+
+.. _coding_conventions:
+
+Coding Guidelines
+=================
+
+General
+-------
+
+|Op_oss| is based on modern C++ (currently C++17). For coding guidelines, please refer to `ISO C++ Core Guidelines <https://github.com/isocpp/CppCoreGuidelines>`_.
+
+**Headers/Sources**
+
+ - Use ``*.h`` as file extension for header files
+ - Use ``*.cpp`` as file extension for source files
+
+Naming Conventions
+------------------
+Concise summarized Naming Conventions
+
+.. literalinclude:: _static/custom_doc/NamingConventions.txt
+
+**Namespaces**
+
+ #. Use lowercase for namespaces
+ #. Use singular form for namespaces where appropriate
+ #. Use base namespace ``openpass``
+ #. Core uses ``openpass::core::*``
+ #. Components use ``openpass::component::*``
+ #. Use the appropriate namespace for the type your component
+
+    * ``openpass::component::algorithm``
+    * ``openpass::component::sensor``
+    * ``openpass::component::dynamics``
+    * ``openpass::component::driver``
+    * ...
+ #. Code with shared scope (e.g. ``common``) namespaces are separated in
+
+    * For everyone ``openpass::common`` e.g. ``openpass::common::XmlParser``
+    * Common for components ``openpass::component::common`` e.g. ``openpass::components::Ports``
+    * For the core only ``openpass::core::common`` e.g. ``openpass::core::common::Parameters``
+
+ #. Discussion: ``openpass::type::*``
+
+    Example: ``openpass::type::Vector2D, openpass::type::OpenDriveId``
+
+**Interfaces**
+
+ #. Interfaces should be named descriptively according to the functionality they outline with an ``UpperCamelCase`` name
+    
+    Example: Interface for the **world** = ``class WorldInterface``
+ #. Interfaces are abstract classes, and as such provide pure virtual functions only, withtout any default implementation. For example:
+
+      ``virtual double GetDistance() const = 0;``
+
+ #. Interface methods **do not** exibit default parameters.
+ #. We excessively use **gmock**, so for every interface a fake interface should be provided 
+    
+    Example: ``class FakeWorld : public WorldInterface {...};``
+    
+    Note: Following ***Roy Osherove***, we use Fake instead of Mock, whick allows to distinguish Mocks and
+    Stubs more easily in the code
+
+**Classes**
+
+ #. Classes should be named descriptively according to the functionality they implement with an ``UpperCamelCase`` name
+ #. A Class implementing an Interface should have the Interfaces name (see below), with the Interface portion removed. For example:
+
+    .. code-block::
+          
+      class AgentBlueprint : public AgentBlueprintInterface {...};
+
+**Methods**
+
+ #. Methods should be descriptively named in ``UpperCamelCase``
+ 
+    Example: Method for retrieving the time of day should be named ``GetTimeOfDay()``
+
+**Member Variables**
+
+ #. Member variables should be descriptively named in ``lowerCamelCase``
+ #. Normally, it is sufficient to use the classes name directly.
+    
+    Example: The member variable containing the AgentNetwork should be named ``agentNetwork``
+
+**Input / Output Signal Naming**
+
+ #. Components use a special form of signal transmission. For easier use, the following abstraction is recommended:
+
+    .. code-block::
+
+      std::map<int, ComponentPort *> outputPorts;
+      bool success = outputPorts.at(localLinkId)->SetSignalValue(data);
+
+    .. code-block::
+
+      std::map<int, ComponentPort *> inputPorts;
+      bool success = inputPorts.at(localLinkId)->GetSignalValue(data);
+
+ #. Discussion: Wrap in ``openpass::components::common::Port`` and further
+    ``openpass::components::common::Ports``
+
+**Additional Information**
+
+ #. Use ``UpperCamelCase`` for abbreviations used in files, classes, methods, or variables
+ #. This does not apply if the abbreviation is the entire name or the beginning of the name - in such a case the name is written with the rules for the appropriate type
+    
+    * int ID→int id
+    * class AgentID→ class AgentId
+    * ADASDriver.cpp→adasDriver.cpp
+ #. Avoid public class data members. If unavoidable, use ``lowerCamelCase``
+ #. Enums should be preferably defined as enum class; as such, enum names should be in ``UpperCamelCase``
+ #. Decorate container by type aliases and use UpperCamelCase. For example:
+
+  .. code-block::
+
+    using FooParts = std::vector<FooPart>;
+
+**Avoid**
+
+ #. Do **not** use Hungarian notation for variables names (iCounter → counter)
+ #. Do **not** specify the type of the underlying implementation (partMap→ parts)
+ #. Do **not** use magic numbers in the code; explicitly define constants instead
+ #. Do **not** use global variables
+
+**Exceptions**
+
+ #. Autogenerated code does not need to follow the coding conventions 
+ 
+    Example:: Signals/Slots (QT): ``void on_button_clicked();``
+
+**Documentation**
+
+ #. The following should be documented
+
+    * Public functions and class methods
+    * Classes
+    * File headers
+    * Constants
+    * Private functions or methods with more than 3 arguments and/or complex functionality??
+
+ #. Language
+
+    * Document "what" it does rather than describing "why"
+    * Third-person singular verbs should be used to describe what it does
+
+ #. Use the below methods to comment in source code. The below 2 syntaxes must be placed just above an entity.
+   
+    Multi line comments
+      
+    .. code-block::
+          
+      //! … comments…
+      //! … comments…
+      //! … comments…
+    
+    Single line comments
+      
+    .. code-block::
+          
+      /// Comments.
+
+ #. Use the following structural commands
+
+    .. list-table::
+       :widths: 25 50
+       :header-rows: 1
+    
+       * - Syntax        
+         - Definition
+       * - @file
+         - The file name must be present in the file header
+       * - @param[in/out]
+         - Parameter documentation for functions
+       * - @page
+         - Markdown page name
+   
+ #. Use the following syntax for parameter description
+   
+    .. code-block::
+    
+      @param[in/out] <variable name> <variable description>
+
+ #. All parameters description should be aligned as shown below to make them more readable.
+   
+    .. code-block::
+    
+     @param[in]  shortName    Description.
+     @param[in]  longerName   Description.
+     @param[out] veryLongName Description.
+
+ #. Example
+ 
+    .. literalinclude:: _static/custom_doc/InlineDocumentation.txt
+
+ #. Do not comment on polymorph methods (virtual base → override), unless there is a severe change
+
+**End Of Line**
+
+ #. Use linux line endings
+ #. Recommendations
+
+    * Under windows add ``git config --local core.autocrlf true`` to your ``.gitconfig`` file
+    * Under linux add ``git config --local core.autocrlf input`` to your ``.gitconfig`` file

doc/source/developer_information/_static/custom_doc/InlineDocumentation.txt

+/// @file main.c
+#include<stdio.h>
+
+/// Mathematical constant PI 
+#define PI       3.1415 
+
+/// Radius in meters  
+#define RADIUS_M 7.82
+ 
+//! Calculates the area of the circle.
+//! 
+//! @param[in]  radius Radius of the circle
+//! @param[out] area   Area of the circle
+float CalculateArea(float radius)
+{
+    float area;
+    area = PI * radius * radius;
+    return area;
+}
\ No newline at end of file

doc/source/developer_information/_static/custom_doc/NamingConventions.txt

+#pragma once
+
+namespace openpass::component::algorithm
+{
+
+/* fooBar.h */                                           // File: lowerCamelCase
+class FooBar                                             // Class: UpperCamelCase
+{
+private:
+    static constexpr int MAGIC_NUMBER {-999};            // Constants: UPPER_CASE
+    int myMember;                                        // Members: lowerCamelCase
+    FooBar();                                            // Ctor: UpperCamelCase
+
+public:
+    void Bar();                                          // Methods: UpperCamelCase
+    void BarBar(bool flag, int counter);                  // Arguments: lowerCamelCase
+    void YaaBar(); /// Yaa = Yet Another Abbreviation    // Abbreviations: UpperCamelCase
+};
+
+}
\ No newline at end of file