Improve docs structure (#467)

- Creates a tree structure for documentation, it allows to organize it better
  from a developer point of view and also the rendered documentation should be
  easier to navigate.
- Moves partially the main readme to be included in the online docs, the main
  readme will be updated to have a link to avoid duplicated content)
- Moves the examples folder to the docs, so they can be accessed through the
  online documentation. Creates a new pair of "macros" to create links to
  specific versions, scm_web & scm_raw_web.

Co-authored-by: Chris Kleinknecht <[email protected]>

Author: mauriciovasquezbernal

docs-requirements.txt

@@ -8,3 +8,6 @@ Deprecated>=1.2.6
 thrift>=0.10.0
 pymongo~=3.1
 flask~=1.0
+mysql-connector-python ~=  8.0
+wrapt >= 1.0.0, < 2.0.0
+psycopg2-binary >= 2.7.3.1

docs/api/api.rst

@@ -30,8 +30,8 @@
 
 # -- Project information -----------------------------------------------------
 
-project = "OpenTelemetry"
-copyright = "2019, OpenTelemetry Authors"  # pylint: disable=redefined-builtin
+project = "OpenTelemetry Python"
+copyright = "OpenTelemetry Authors"  # pylint: disable=redefined-builtin
 author = "OpenTelemetry Authors"
 
 
@@ -57,6 +57,8 @@
     # Add a .nojekyll file to the generated HTML docs
     # https://help.github.com/en/articles/files-that-start-with-an-underscore-are-missing
     "sphinx.ext.githubpages",
+    # Support external links to different versions in the Github repo
+    "sphinx.ext.extlinks",
 ]
 
 intersphinx_mapping = {
@@ -106,3 +108,27 @@
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
 html_static_path = []
+
+# Support external links to specific versions of the files in the Github repo
+branch = os.environ.get("READTHEDOCS_VERSION")
+if branch is None or branch == "latest":
+    branch = "master"
+
+REPO = "open-telemetry/opentelemetry-python/"
+scm_raw_web = "https://raw.githubusercontent.com/" + REPO + branch
+scm_web = "https://github.com/" + REPO + "blob/" + branch
+
+# Store variables in the epilogue so they are globally available.
+rst_epilog = """
+.. |SCM_WEB| replace:: {s}
+.. |SCM_RAW_WEB| replace:: {sr}
+.. |SCM_BRANCH| replace:: {b}
+""".format(
+    s=scm_web, sr=scm_raw_web, b=branch
+)
+
+# used to have links to repo files
+extlinks = {
+    "scm_raw_web": (scm_raw_web + "/%s", "scm_raw_web"),
+    "scm_web": (scm_web + "/%s", "scm_web"),
+}