Skip to content

Commit d5f3a7f

Browse files
Improve docs structure (open-telemetry#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 <libc@google.com>
1 parent 9850fb3 commit d5f3a7f

File tree

79 files changed

+560
-372
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

79 files changed

+560
-372
lines changed

docs-requirements.txt

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,3 +8,6 @@ Deprecated>=1.2.6
88
thrift>=0.10.0
99
pymongo~=3.1
1010
flask~=1.0
11+
mysql-connector-python ~= 8.0
12+
wrapt >= 1.0.0, < 2.0.0
13+
psycopg2-binary >= 2.7.3.1

docs/api/api.rst

Lines changed: 12 additions & 0 deletions

docs/opentelemetry.context.rst renamed to docs/api/context.rst

Lines changed: 1 addition & 1 deletion

docs/opentelemetry.trace.rst renamed to docs/api/trace.rst

Lines changed: 2 additions & 2 deletions

docs/conf.py

Lines changed: 28 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -30,8 +30,8 @@
3030

3131
# -- Project information -----------------------------------------------------
3232

33-
project = "OpenTelemetry"
34-
copyright = "2019, OpenTelemetry Authors" # pylint: disable=redefined-builtin
33+
project = "OpenTelemetry Python"
34+
copyright = "OpenTelemetry Authors" # pylint: disable=redefined-builtin
3535
author = "OpenTelemetry Authors"
3636

3737

@@ -57,6 +57,8 @@
5757
# Add a .nojekyll file to the generated HTML docs
5858
# https://help.github.com/en/articles/files-that-start-with-an-underscore-are-missing
5959
"sphinx.ext.githubpages",
60+
# Support external links to different versions in the Github repo
61+
"sphinx.ext.extlinks",
6062
]
6163

6264
intersphinx_mapping = {
@@ -106,3 +108,27 @@
106108
# relative to this directory. They are copied after the builtin static files,
107109
# so a file named "default.css" will overwrite the builtin "default.css".
108110
html_static_path = []
111+
112+
# Support external links to specific versions of the files in the Github repo
113+
branch = os.environ.get("READTHEDOCS_VERSION")
114+
if branch is None or branch == "latest":
115+
branch = "master"
116+
117+
REPO = "open-telemetry/opentelemetry-python/"
118+
scm_raw_web = "https://raw.githubusercontent.com/" + REPO + branch
119+
scm_web = "https://github.com/" + REPO + "blob/" + branch
120+
121+
# Store variables in the epilogue so they are globally available.
122+
rst_epilog = """
123+
.. |SCM_WEB| replace:: {s}
124+
.. |SCM_RAW_WEB| replace:: {sr}
125+
.. |SCM_BRANCH| replace:: {b}
126+
""".format(
127+
s=scm_web, sr=scm_raw_web, b=branch
128+
)
129+
130+
# used to have links to repo files
131+
extlinks = {
132+
"scm_raw_web": (scm_raw_web + "/%s", "scm_raw_web"),
133+
"scm_web": (scm_web + "/%s", "scm_web"),
134+
}

docs/examples/basic_tracer/README.rst

Lines changed: 76 additions & 0 deletions

docs/examples/http/README.rst

Lines changed: 87 additions & 0 deletions
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.

docs/examples/opentracing/README.rst

Lines changed: 97 additions & 0 deletions
File renamed without changes.

docs/ext/dbapi/dbapi.rst

Lines changed: 10 additions & 0 deletions

docs/opentelemetry.ext.flask.rst renamed to docs/ext/flask/flask.rst

Lines changed: 2 additions & 2 deletions

docs/opentelemetry.ext.http_requests.rst renamed to docs/ext/http_requests/http_requests.rst

Lines changed: 1 addition & 2 deletions

docs/ext/jaeger/jaeger.rst

Lines changed: 17 additions & 0 deletions

0 commit comments

Comments
 (0)