Fix ReadTheDocs headers and sections order for 8 Instrumentors (#3719)

* Fix readthedocs headers

* Changelog

* Add header

Author: tammy-baylis-swi

CHANGELOG.md

@@ -18,15 +18,17 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - `opentelemetry-instrumentation-asgi`: Make all user hooks failsafe and record exceptions in hooks.
   ([#3664](https://github.com/open-telemetry/opentelemetry-python-contrib/pull/3664))
 - `opentelemetry-instrumentation-fastapi`: Fix memory leak in `uninstrument_app()` by properly removing apps from the tracking set
-  ([#3688](https://github.com/open-telemetry/opentelemetry-python-contrib/pull/3688)
-- `opentelemetry-instrumentation-tornado`: Fix server (request) duration metric calculation
+  ([#3688](https://github.com/open-telemetry/opentelemetry-python-contrib/pull/3688))
+- `opentelemetry-instrumentation-tornado` Fix server (request) duration metric calculation
   ([#3679](https://github.com/open-telemetry/opentelemetry-python-contrib/pull/3679))
 - `opentelemetry-instrumentation-tornado`: Fix to properly skip all server telemetry when URL excluded.
   ([#3680](https://github.com/open-telemetry/opentelemetry-python-contrib/pull/3680))
 - `opentelemetry-instrumentation`: Avoid calls to `context.detach` with `None` token.
   ([#3673](https://github.com/open-telemetry/opentelemetry-python-contrib/pull/3673))
 - `opentelemetry-instrumentation-starlette`/`opentelemetry-instrumentation-fastapi`: Fixes a crash when host-based routing is used
   ([#3507](https://github.com/open-telemetry/opentelemetry-python-contrib/pull/3507))
+- Fix documentation order of sections and headers for Django, Flask, MySQL, mysqlclient, psycopg, psycopg2, pymysql, sqlalchemy instrumentations.
+  ([#3719](https://github.com/open-telemetry/opentelemetry-python-contrib/pull/3719))
 
 ### Added
 

instrumentation/opentelemetry-instrumentation-django/src/opentelemetry/instrumentation/django/__init__.py

@@ -17,68 +17,6 @@
 
 .. _django: https://pypi.org/project/django/
 
-SQLCOMMENTER
-*****************************************
-You can optionally configure Django instrumentation to enable sqlcommenter which enriches
-the query with contextual information.
-
-Usage
------
-
-.. code:: python
-
-    from opentelemetry.instrumentation.django import DjangoInstrumentor
-
-    DjangoInstrumentor().instrument(is_sql_commentor_enabled=True)
-
-
-For example,
-::
-
-   Invoking Users().objects.all() will lead to sql query "select * from auth_users" but when SQLCommenter is enabled
-   the query will get appended with some configurable tags like "select * from auth_users /*metrics=value*/;"
-
-
-SQLCommenter Configurations
-***************************
-We can configure the tags to be appended to the sqlquery log by adding below variables to the settings.py
-
-SQLCOMMENTER_WITH_FRAMEWORK = True(Default) or False
-
-For example,
-::
-Enabling this flag will add django framework and it's version which is /*framework='django%3A2.2.3*/
-
-SQLCOMMENTER_WITH_CONTROLLER = True(Default) or False
-
-For example,
-::
-Enabling this flag will add controller name that handles the request /*controller='index'*/
-
-SQLCOMMENTER_WITH_ROUTE = True(Default) or False
-
-For example,
-::
-Enabling this flag will add url path that handles the request /*route='polls/'*/
-
-SQLCOMMENTER_WITH_APP_NAME = True(Default) or False
-
-For example,
-::
-Enabling this flag will add app name that handles the request /*app_name='polls'*/
-
-SQLCOMMENTER_WITH_OPENTELEMETRY = True(Default) or False
-
-For example,
-::
-Enabling this flag will add opentelemetry traceparent /*traceparent='00-fd720cffceba94bbf75940ff3caaf3cc-4fd1a2bdacf56388-01'*/
-
-SQLCOMMENTER_WITH_DB_DRIVER = True(Default) or False
-
-For example,
-::
-Enabling this flag will add name of the db driver /*db_driver='django.db.backends.postgresql'*/
-
 Usage
 -----
 
@@ -232,6 +170,65 @@ def response_hook(span, request, response):
 Note:
     The environment variable names used to capture HTTP headers are still experimental, and thus are subject to change.
 
+SQLCOMMENTER
+*****************************************
+You can optionally configure Django instrumentation to enable sqlcommenter which enriches
+the query with contextual information.
+
+.. code:: python
+
+    from opentelemetry.instrumentation.django import DjangoInstrumentor
+
+    DjangoInstrumentor().instrument(is_sql_commentor_enabled=True)
+
+
+For example,
+::
+
+   Invoking Users().objects.all() will lead to sql query "select * from auth_users" but when SQLCommenter is enabled
+   the query will get appended with some configurable tags like "select * from auth_users /*metrics=value*/;"
+
+
+SQLCommenter Configurations
+***************************
+We can configure the tags to be appended to the sqlquery log by adding below variables to the settings.py
+
+SQLCOMMENTER_WITH_FRAMEWORK = True(Default) or False
+
+For example,
+::
+Enabling this flag will add django framework and it's version which is /*framework='django%3A2.2.3*/
+
+SQLCOMMENTER_WITH_CONTROLLER = True(Default) or False
+
+For example,
+::
+Enabling this flag will add controller name that handles the request /*controller='index'*/
+
+SQLCOMMENTER_WITH_ROUTE = True(Default) or False
+
+For example,
+::
+Enabling this flag will add url path that handles the request /*route='polls/'*/
+
+SQLCOMMENTER_WITH_APP_NAME = True(Default) or False
+
+For example,
+::
+Enabling this flag will add app name that handles the request /*app_name='polls'*/
+
+SQLCOMMENTER_WITH_OPENTELEMETRY = True(Default) or False
+
+For example,
+::
+Enabling this flag will add opentelemetry traceparent /*traceparent='00-fd720cffceba94bbf75940ff3caaf3cc-4fd1a2bdacf56388-01'*/
+
+SQLCOMMENTER_WITH_DB_DRIVER = True(Default) or False
+
+For example,
+::
+Enabling this flag will add name of the db driver /*db_driver='django.db.backends.postgresql'*/
+
 API
 ---
 

instrumentation/opentelemetry-instrumentation-flask/src/opentelemetry/instrumentation/flask/__init__.py

@@ -24,58 +24,6 @@
 * The ``http.route`` Span attribute is set so that one can see which URL rule
   matched a request.
 
-SQLCOMMENTER
-*****************************************
-You can optionally configure Flask instrumentation to enable sqlcommenter which enriches
-the query with contextual information.
-
-Usage
------
-
-.. code:: python
-
-    from opentelemetry.instrumentation.flask import FlaskInstrumentor
-
-    FlaskInstrumentor().instrument(enable_commenter=True, commenter_options={})
-
-For example, FlaskInstrumentor when used with SQLAlchemyInstrumentor or Psycopg2Instrumentor,
-invoking ``cursor.execute("select * from auth_users")`` will lead to sql query
-``select * from auth_users`` but when SQLCommenter is enabled the query will get appended with
-some configurable tags like:
-
-.. code::
-
-    select * from auth_users /*metrics=value*/;"
-
-Inorder for the commenter to append flask related tags to sql queries, the commenter needs
-to enabled on the respective SQLAlchemyInstrumentor or Psycopg2Instrumentor framework too.
-
-SQLCommenter Configurations
-***************************
-We can configure the tags to be appended to the sqlquery log by adding configuration
-inside ``commenter_options={}`` dict.
-
-For example, enabling this flag will add flask and it's version which
-is ``/*flask%%3A2.9.3*/`` to the SQL query as a comment (default is True):
-
-.. code:: python
-
-    framework = True
-
-For example, enabling this flag will add route uri ``/*route='/home'*/``
-to the SQL query as a comment (default is True):
-
-.. code:: python
-
-    route = True
-
-For example, enabling this flag will add controller name ``/*controller='home_view'*/``
-to the SQL query as a comment (default is True):
-
-.. code:: python
-
-    controller = True
-
 Usage
 -----
 
@@ -241,6 +189,55 @@ def response_hook(span: Span, status: str, response_headers: List):
 Note:
     The environment variable names used to capture HTTP headers are still experimental, and thus are subject to change.
 
+SQLCOMMENTER
+*****************************************
+You can optionally configure Flask instrumentation to enable sqlcommenter which enriches
+the query with contextual information.
+
+.. code:: python
+
+    from opentelemetry.instrumentation.flask import FlaskInstrumentor
+
+    FlaskInstrumentor().instrument(enable_commenter=True, commenter_options={})
+
+For example, FlaskInstrumentor when used with SQLAlchemyInstrumentor or Psycopg2Instrumentor,
+invoking ``cursor.execute("select * from auth_users")`` will lead to sql query
+``select * from auth_users`` but when SQLCommenter is enabled the query will get appended with
+some configurable tags like:
+
+.. code::
+
+    select * from auth_users /*metrics=value*/;"
+
+Inorder for the commenter to append flask related tags to sql queries, the commenter needs
+to enabled on the respective SQLAlchemyInstrumentor or Psycopg2Instrumentor framework too.
+
+SQLCommenter Configurations
+***************************
+We can configure the tags to be appended to the sqlquery log by adding configuration
+inside ``commenter_options={}`` dict.
+
+For example, enabling this flag will add flask and it's version which
+is ``/*flask%%3A2.9.3*/`` to the SQL query as a comment (default is True):
+
+.. code:: python
+
+    framework = True
+
+For example, enabling this flag will add route uri ``/*route='/home'*/``
+to the SQL query as a comment (default is True):
+
+.. code:: python
+
+    route = True
+
+For example, enabling this flag will add controller name ``/*controller='home_view'*/``
+to the SQL query as a comment (default is True):
+
+.. code:: python
+
+    controller = True
+
 API
 ---
 """

instrumentation/opentelemetry-instrumentation-mysql/src/opentelemetry/instrumentation/mysql/__init__.py

@@ -50,13 +50,13 @@
     cursor.close()
     instrumented_cnx.close()
 
+Configuration
+-------------
+
 SQLCOMMENTER
 *****************************************
 You can optionally configure mysql-connector instrumentation to enable sqlcommenter which enriches the query with contextual information.
 
-Usage
------
-
 .. code:: python
 
     import mysql.connector
@@ -70,7 +70,6 @@
     cursor.close()
     cnx.close()
 
-
 For example,
 ::
 

instrumentation/opentelemetry-instrumentation-mysqlclient/src/opentelemetry/instrumentation/mysqlclient/__init__.py

@@ -36,6 +36,9 @@
     cursor.close()
     cnx.close()
 
+Configuration
+-------------
+
 SQLCOMMENTER
 *****************************************
 You can optionally configure MySQLClient instrumentation to enable sqlcommenter which enriches