chore: fix md based on rules and fix bad links (#2240)

* chore: fix md based on rules and fix bad links

* chore: add index to contribuiting and readme files

---------

Co-authored-by: Leighton Chen <lechen@microsoft.com>
Co-authored-by: Shalev Roda <65566801+shalevr@users.noreply.github.com>

CONTRIBUTING.md

@@ -13,7 +13,26 @@ on how to become a [**Member**](https://github.com/open-telemetry/community/blob
 [**Approver**](https://github.com/open-telemetry/community/blob/main/community-membership.md#approver)
 and [**Maintainer**](https://github.com/open-telemetry/community/blob/main/community-membership.md#maintainer).
 
-## Find a Buddy and get Started Quickly!
+## Index
+
+* [Find a Buddy and get Started Quickly](#find-a-buddy-and-get-started-quickly)
+* [Development](#development)
+  * [Troubleshooting](#troubleshooting)
+  * [Benchmarks](#benchmarks)
+* [Pull requests](#pull-requests)
+  * [How to Send Pull Requests](#how-to-send-pull-requests)
+  * [How to Receive Comments](#how-to-receive-comments)
+  * [How to Get PRs Reviewed](#how-to-get-prs-reviewed)
+  * [How to Get PRs Merged](#how-to-get-prs-merged)
+* [Design Choices](#design-choices)
+  * [Focus on Capabilities, Not Structure Compliance](#focus-on-capabilities-not-structure-compliance)
+* [Running Tests Locally](#running-tests-locally)
+  * [Testing against a different Core repo branch/commit](#testing-against-a-different-core-repo-branchcommit)
+* [Style Guide](#style-guide)
+* [Guideline for instrumentations](#guideline-for-instrumentations)
+* [Expectations from contributors](#expectations-from-contributors)
+
+## Find a Buddy and get Started Quickly
 
 If you are looking for someone to help you find a starting point and be a resource for your first contribution, join our
 Slack and find a buddy!
@@ -31,8 +50,8 @@ This project uses [tox](https://tox.readthedocs.io) to automate
 some aspects of development, including testing against multiple Python versions.
 To install `tox`, run:
 
-```console
-$ pip install tox
+```sh
+pip install tox
 ```
 
 You can run `tox` with the following arguments:
@@ -57,7 +76,7 @@ for more detail on available tox commands.
 
 ### Troubleshooting
 
-- Some packages may require additional system wide dependencies to be installed. For example, you may need to install `libpq-dev` to run the postgresql client libraries instrumentation tests. or `libsnappy-dev` to run the prometheus exporter tests. If you encounter a build error, please check the installation instructions for the package you are trying to run tests for.
+> Some packages may require additional system wide dependencies to be installed. For example, you may need to install `libpq-dev` to run the postgresql client libraries instrumentation tests. or `libsnappy-dev` to run the prometheus exporter tests. If you encounter a build error, please check the installation instructions for the package you are trying to run tests for.
 
 ### Benchmarks
 
@@ -94,13 +113,13 @@ pull requests (PRs).
 To create a new PR, fork the project in GitHub and clone the upstream repo:
 
 ```sh
-$ git clone https://github.com/open-telemetry/opentelemetry-python-contrib.git
+git clone https://github.com/open-telemetry/opentelemetry-python-contrib.git
 ```
 
 Add your fork as an origin:
 
 ```sh
-$ git remote add fork https://github.com/YOUR_GITHUB_USERNAME/opentelemetry-python-contrib.git
+git remote add fork https://github.com/YOUR_GITHUB_USERNAME/opentelemetry-python-contrib.git
 ```
 
 Run tests:
@@ -114,10 +133,10 @@ $ tox  # execute in the root of the repository
 Check out a new branch, make modifications and push the branch to your fork:
 
 ```sh
-$ git checkout -b feature
+git checkout -b feature
 # edit files
-$ git commit
-$ git push fork feature
+git commit
+git push fork feature
 ```
 
 Open a pull request against the main `opentelemetry-python-contrib` repo.
@@ -142,6 +161,7 @@ If you are not getting reviews, please contact the respective owners directly.
 ### How to Get PRs Merged
 
 A PR is considered to be **ready to merge** when:
+
 * It has received two approvals from [Approvers](https://github.com/open-telemetry/community/blob/main/community-membership.md#approver)
   / [Maintainers](https://github.com/open-telemetry/community/blob/main/community-membership.md#maintainer)
   (at different companies).
@@ -186,8 +206,7 @@ Some of the tox targets install packages from the [OpenTelemetry Python Core Rep
 
 CORE_REPO_SHA=c49ad57bfe35cfc69bfa863d74058ca9bec55fc3 tox
 
-The continuation integration overrides that environment variable with as per the configuration [here](https://github.com/open-telemetry/opentelemetry-python-contrib/blob/main/.github/workflows/test.yml#L9).
-
+The continuation integration overrides that environment variable with as per the configuration [here](https://github.com/open-telemetry/opentelemetry-python-contrib/blob/2518a4ac07cb62ad6587dd8f6cbb5f8663a7e179/.github/workflows/test.yml#L9).
 
 ## Style Guide
 
@@ -203,27 +222,25 @@ Below is a checklist of things to be mindful of when implementing a new instrume
 
 - Follow semantic conventions
   - The instrumentation should follow the semantic conventions defined [here](https://github.com/open-telemetry/opentelemetry-specification/tree/main/specification/semantic-conventions.md)
-- Extends from [BaseInstrumentor](https://github.com/open-telemetry/opentelemetry-python-contrib/blob/main/opentelemetry-instrumentation/src/opentelemetry/instrumentation/instrumentor.py#L26)
+- Extends from [BaseInstrumentor](https://github.com/open-telemetry/opentelemetry-python-contrib/blob/2518a4ac07cb62ad6587dd8f6cbb5f8663a7e179/opentelemetry-instrumentation/src/opentelemetry/instrumentation/instrumentor.py#L35)
 - Supports auto-instrumentation
-  - Add an entry point (ex. https://github.com/open-telemetry/opentelemetry-python-contrib/blob/f045c43affff6ff1af8fa2f7514a4fdaca97dacf/instrumentation/opentelemetry-instrumentation-requests/pyproject.toml#L44)
+  - Add an entry point (ex. <https://github.com/open-telemetry/opentelemetry-python-contrib/blob/2518a4ac07cb62ad6587dd8f6cbb5f8663a7e179/instrumentation/opentelemetry-instrumentation-requests/pyproject.toml#L44>)
   - Run `python scripts/generate_instrumentation_bootstrap.py` after adding a new instrumentation package.
 - Functionality that is common amongst other instrumentation and can be abstracted [here](https://github.com/open-telemetry/opentelemetry-python-contrib/tree/main/opentelemetry-instrumentation/src/opentelemetry/instrumentation)
 - Request/response [hooks](https://github.com/open-telemetry/opentelemetry-python-contrib/issues/408) for http instrumentations
 - `suppress_instrumentation` functionality
-  - ex. https://github.com/open-telemetry/opentelemetry-python-contrib/blob/3ec77360cb20482b08b30312a6bedc8b946e3fa1/instrumentation/opentelemetry-instrumentation-requests/src/opentelemetry/instrumentation/requests/__init__.py#L111
+  - ex. <https://github.com/open-telemetry/opentelemetry-python-contrib/blob/2518a4ac07cb62ad6587dd8f6cbb5f8663a7e179/opentelemetry-instrumentation/src/opentelemetry/instrumentation/utils.py#L191>
 - Suppress propagation functionality
   - https://github.com/open-telemetry/opentelemetry-python-contrib/issues/344 for more context
 - `exclude_urls` functionality
-  - ex. https://github.com/open-telemetry/opentelemetry-python-contrib/blob/0fcb60d2ad139f78a52edd85b1cc4e32f2e962d0/instrumentation/opentelemetry-instrumentation-flask/src/opentelemetry/instrumentation/flask/__init__.py#L91
+  - ex. <https://github.com/open-telemetry/opentelemetry-python-contrib/blob/2518a4ac07cb62ad6587dd8f6cbb5f8663a7e179/instrumentation/opentelemetry-instrumentation-flask/src/opentelemetry/instrumentation/flask/__init__.py#L327>
 - `url_filter` functionality
-  - ex. https://github.com/open-telemetry/opentelemetry-python-contrib/blob/0fcb60d2ad139f78a52edd85b1cc4e32f2e962d0/instrumentation/opentelemetry-instrumentation-aiohttp-client/src/opentelemetry/instrumentation/aiohttp_client/__init__.py#L235
+  - ex. <https://github.com/open-telemetry/opentelemetry-python-contrib/blob/2518a4ac07cb62ad6587dd8f6cbb5f8663a7e179/instrumentation/opentelemetry-instrumentation-aiohttp-client/src/opentelemetry/instrumentation/aiohttp_client/__init__.py#L268>
 - `is_recording()` optimization on non-sampled spans
-  - ex. https://github.com/open-telemetry/opentelemetry-python-contrib/blob/main/instrumentation/opentelemetry-instrumentation-requests/src/opentelemetry/instrumentation/requests/__init__.py#L133
+  - ex. <https://github.com/open-telemetry/opentelemetry-python-contrib/blob/2518a4ac07cb62ad6587dd8f6cbb5f8663a7e179/instrumentation/opentelemetry-instrumentation-requests/src/opentelemetry/instrumentation/requests/__init__.py#L234>
 - Appropriate error handling
-  - ex. https://github.com/open-telemetry/opentelemetry-python-contrib/blob/main/instrumentation/opentelemetry-instrumentation-requests/src/opentelemetry/instrumentation/requests/__init__.py#L146
-
+  - ex. <https://github.com/open-telemetry/opentelemetry-python-contrib/blob/2518a4ac07cb62ad6587dd8f6cbb5f8663a7e179/instrumentation/opentelemetry-instrumentation-requests/src/opentelemetry/instrumentation/requests/__init__.py#L220>
 
 ## Expectations from contributors
 
 OpenTelemetry is an open source community, and as such, greatly encourages contributions from anyone interested in the project. With that being said, there is a certain level of expectation from contributors even after a pull request is merged, specifically pertaining to instrumentations. The OpenTelemetry Python community expects contributors to maintain a level of support and interest in the instrumentations they contribute. This is to ensure that the instrumentation does not become stale and still functions the way the original contributor intended. Some instrumentations also pertain to libraries that the current members of the community are not so familiar with, so it is necessary to rely on the expertise of the original contributing parties.
-

README.md

@@ -36,11 +36,20 @@
 
 ---
 
-## OpenTelemetry Python Contrib
+# OpenTelemetry Python Contrib
 
 The Python auto-instrumentation libraries for [OpenTelemetry](https://opentelemetry.io/) (per [OTEP 0001](https://github.com/open-telemetry/oteps/blob/main/text/0001-telemetry-without-manual-instrumentation.md))
 
-### Installation
+## Index
+
+* [Installation](#installation)
+* [Releasing](#releasing)
+  * [Releasing a package as `1.0` stable](#releasing-a-package-as-10-stable)
+* [Contributing](#contributing)
+* [Running Tests Locally](#running-tests-locally)
+* [Thanks to all the people who already contributed](#thanks-to-all-the-people-who-already-contributed)
+
+## Installation
 
 This repository includes installable packages for each instrumented library. Libraries that produce telemetry data should only depend on `opentelemetry-api`,
 and defer the choice of the SDK to the application developer. Applications may
@@ -79,6 +88,7 @@ To resolve this, members of the community are encouraged to commit to becoming a
 ### Releasing a package as `1.0` stable
 
 To release a package as `1.0` stable, the package:
+
 - SHOULD have a CODEOWNER. To become one, submit an issue and explain why you meet the responsibilities found in [CODEOWNERS](.github/CODEOWNERS).
 - MUST have unit tests that cover all supported versions of the instrumented library.
   - e.g. Instrumentation packages might use different techniques to instrument different major versions of python packages
@@ -131,9 +141,8 @@ Emeritus Maintainers:
 4. Make sure you have `tox` installed. `pip install tox`.
 5. Run tests for a package. (e.g. `tox -e test-instrumentation-flask`.)
 
-### Thanks to all the people who already contributed!
+### Thanks to all the people who already contributed
 
 <a href="https://github.com/open-telemetry/opentelemetry-python-contrib/graphs/contributors">
   <img src="https://contributors-img.web.app/image?repo=open-telemetry/opentelemetry-python-contrib" />
 </a>
-

RELEASING.md

@@ -77,15 +77,17 @@
   * If for some reason the action failed, see [Publish failed](#publish-failed) below
 * Move stable tag
   * Run the following (TODO automate):
+
     ```bash
     git tag -d stable
     git tag stable
     git push --delete origin tagname
     git push origin stable
     ```
+
   * This will ensure the docs are pointing at the stable release.
   * To validate this worked, ensure the stable build has run successfully:
-    https://readthedocs.org/projects/opentelemetry-python/builds/.
+    <https://readthedocs.org/projects/opentelemetry-python/builds/>.
     If the build has not run automatically, it can be manually trigger via the readthedocs interface.
 
 ## Troubleshooting
@@ -98,4 +100,4 @@ If for some reason the action failed, do it manually:
 - Build distributions with `./scripts/build.sh`
 - Delete distributions we don't want to push (e.g. `testutil`)
 - Push to PyPI as `twine upload --skip-existing --verbose dist/*`
-- Double check PyPI!
+- Double check PyPI!