Build and host docs via github action #167

c24t · 2019-09-24T22:00:56Z

Docs are live! See https://open-telemetry.github.io/opentelemetry-python/index.html.

Fixes #9.

This PR adds a github action that builds the docs and copies them to the gh-pages branch on each push to master.

We do the same thing in OpenCensus, but via travis. OC's docs are here: https://census-instrumentation.github.io/opencensus-python/.

Note that this uses the third-party action JamesIves/github-pages-deploy-action (see entrypoint.sh for details). I had to create a new personal access token for this action, the built-in GITHUB_TOKEN token doesn't work.

Some things we could still improve:

Host multiple versions of the docs, a la https://readthedocs.org
Default to displaying docs for the last-released version of the library instead of the version on master
Don't rebuild docs unless source files have changed
Automate running sphinx-apidoc to update sources

Because of JamesIves/github-pages-deploy-action#5

Oberon00

Sorry for the nitpicks 😄 Nice work 🎉

Oberon00 · 2019-09-25T08:45:20Z

.github/workflows/docs.yml

+name: Docs
+
+on:
+  push:


Is there also a trigger for "on successful build/checks"? That would probably be better than on every push.

This should only trigger on pushes to the master branch, so after a PR has been merged. At that point the checks should have already passed. Another option is to rebuild the docs on releases, but at least for now I think it's helpful to have the docs track master.

See also the workflow syntax docs and event descriptions.

Oberon00 · 2019-09-25T08:46:32Z

.github/workflows/docs.yml

+    - uses: actions/setup-python@v1
+    - name: Build docs
+      run: |
+        pip install tox


Probably we should use pip install tox~=VERSION here, or pip install --upgrade tox.

As I understand it we get a fresh virtual environment for each run, but I suppose there's no reason not to use --upgrade.

I think it's fine to use current tox here since the dependency won't affect users, and there's some benefit to staying up to date.

Oberon00 · 2019-09-25T08:47:49Z

tox.ini

@@ -96,3 +96,6 @@ changedir = docs

 commands =
  sphinx-build -W --keep-going -b html -T . _build/html
+  ; stop jekyll from running on gh-pages
+  ; https://help.github.com/en/articles/files-that-start-with-an-underscore-are-missing
+  touch _build/html/.nojekyll


Instead of this touch we could also use https://www.sphinx-doc.org/en/master/usage/extensions/githubpages.html. Makes it easier to build without tox.

Good find! Added in 2f3e42f.

for start_time and end_time Make lint happy Addressing comments Addressing comments Allowing 0 as start and end time Fix lint issues Metrics API RFC 0003 cont'd (open-telemetry#136) * Create functions Comments for Meter More comments Add more comments Fix typos * fix lint * Fix lint * fix typing * Remove options, constructors, seperate labels * Consistent naming for float and int * Abstract time series * Use ABC * Fix typo * Fix docs * seperate measure classes * Add examples * fix lint * Update to RFC 0003 * Add spancontext, measurebatch * Fix docs * Fix comments * fix lint * fix lint * fix lint * skip examples * white space * fix spacing * fix imports * fix imports * LabelValues to str * Black formatting * fix isort * Remove aggregation * Fix names * Remove aggregation from docs * Fix lint * metric changes * Typing * Fix lint * Fix lint * Add space * Fix lint * fix comments * address comments * fix comments Adding a working propagator, adding to integrations and example (open-telemetry#137) Adding a full, end-to-end example of propagation at work in the example application, including a test. Adding the use of propagators into the integrations. Metrics API RFC 0009 (open-telemetry#140) * Create functions Comments for Meter More comments Add more comments Fix typos * fix lint * Fix lint * fix typing * Remove options, constructors, seperate labels * Consistent naming for float and int * Abstract time series * Use ABC * Fix typo * Fix docs * seperate measure classes * Add examples * fix lint * Update to RFC 0003 * Add spancontext, measurebatch * Fix docs * Fix comments * fix lint * fix lint * fix lint * skip examples * white space * fix spacing * fix imports * fix imports * LabelValues to str * Black formatting * fix isort * Remove aggregation * Fix names * Remove aggregation from docs * Fix lint * metric changes * Typing * Fix lint * Fix lint * Add space * Fix lint * fix comments * handle, recordbatch * docs * Update recordbatch * black * Fix typo * remove ValueType * fix lint Console exporter (open-telemetry#156) Make use_span more flexible (closes open-telemetry#147). (open-telemetry#154) Co-Authored-By: Reiley Yang <reyang@microsoft.com> Co-Authored-By: Chris Kleinknecht <libc@google.com> WSGI fixes (open-telemetry#148) Fix http.url. Don't delay calling wrapped app. Skeleton for azure monitor exporters (open-telemetry#151) Add link to docs to README (open-telemetry#170) Move example app to the examples folder (open-telemetry#172) WSGI: Fix port 80 always appended in http.host (open-telemetry#173) Build and host docs via github action (open-telemetry#167) Add missing license boilerplate to a few files (open-telemetry#176) sdk/trace/exporters: add batch span processor exporter (open-telemetry#153) The exporters specification states that two built-in span processors should be implemented, the simple processor span and the batch processor span. This commit implements the latter, it is mainly based on the opentelemetry/java one. The algorithm implements the following logic: - a condition variable is used to notify the worker thread in case the queue is half full, so that exporting can start before the queue gets full and spans are dropped. - export is called each schedule_delay_millis if there is a least one new span to export. - when the processor is shutdown all remaining spans are exported. Implementing W3C TraceContext (fixes open-telemetry#116) (open-telemetry#180) * Implementing TraceContext (fixes open-telemetry#116) This introduces a w3c TraceContext propagator, primarily inspired by opencensus. fix time conversion bug (open-telemetry#182) Introduce Context.suppress_instrumentation (open-telemetry#181) Metrics Implementation (open-telemetry#160) * Create functions Comments for Meter More comments Add more comments Fix typos * fix lint * Fix lint * fix typing * Remove options, constructors, seperate labels * Consistent naming for float and int * Abstract time series * Use ABC * Fix typo * Fix docs * seperate measure classes * Add examples * fix lint * Update to RFC 0003 * Add spancontext, measurebatch * Fix docs * Fix comments * fix lint * fix lint * fix lint * skip examples * white space * fix spacing * fix imports * fix imports * LabelValues to str * Black formatting * fix isort * Remove aggregation * Fix names * Remove aggregation from docs * Fix lint * metric changes * Typing * Fix lint * Fix lint * Add space * Fix lint * fix comments * handle, recordbatch * docs * Update recordbatch * black * Fix typo * remove ValueType * fix lint * sdk * metrics * example * counter * Tests * Address comments * ADd tests * Fix typing and examples * black * fix lint * remove override * Fix tests * mypy * fix lint * fix type * fix typing * fix tests * isort * isort * isort * isort * noop * lint * lint * fix tuple typing * fix type * black * address comments * fix type * fix lint * remove imports * default tests * fix lint * usse sequence * remove ellipses * remove ellipses * black * Fix typo * fix example * fix type * fix type * address comments Implement Azure Monitor Exporter (open-telemetry#175) Span add override parameters for start_time and end_time (open-telemetry#179) CONTRIBUTING.md: Fix clone URL (open-telemetry#177) Add B3 exporter to alpha release table (open-telemetry#164) Update README for alpha release (open-telemetry#189) Update Contributing.md doc (open-telemetry#194) Add **simple** client/server examples (open-telemetry#191) Remove unused dev-requirements.txt (open-telemetry#200) The requirements are contained in tox.ini now. Fx bug in BoundedList for Python 3.4 and add tests (open-telemetry#199) * fix bug in BoundedList for python 3.4 and add tests collections.deque.copy() was introduced in python 3.5, this commit changes that by the deque constructor and adds some tests to BoundedList and BoundedDict to avoid similar problems in the future. Also, improve docstrings of BoundedList and BoundedDict classes Move util.time_ns to API. (open-telemetry#205) Add Jaeger exporter (open-telemetry#174) This adds a Jeager exporter for OpenTelemetry. This exporter is based on https://github.com/census-instrumentation/opencensus-python/tree/master/contrib/opencensus-ext-jaeger. The exporter uses thrift and can be configured to send data to the agent and also to a remote collector. There is a long discussion going on about how to include generated files in the repo, so for now just put them here. Add code coverage Revert latest commit Fix some "errors" found by mypy. (open-telemetry#204) Fix some errors found by mypy (split from open-telemetry#201). Update README for new milestones (open-telemetry#218) Refactor current span handling for newly created spans. (open-telemetry#198) 1. Make Tracer.start_span() simply create and start the Span, without setting it as the current instance. 2. Add an extra Tracer.start_as_current_span() to create the Span and set it as the current instance automatically. Co-Authored-By: Chris Kleinknecht <libc@google.com> Add set_status to Span (open-telemetry#213) Initial commit Initial version

* feat(sdk): add No Recording Span implementation Closes open-telemetry/opentelemetry-js#119. * Fixes typo * adds missing license header

c24t requested review from a-feld, carlosalberto, lzchen, Oberon00, reyang and toumorokoshi as code owners September 24, 2019 22:00

c24t mentioned this pull request Sep 24, 2019

Test GH actions to lint #168

Closed

c24t force-pushed the c24t-patch-1 branch 13 times, most recently from d02b794 to f0c8948 Compare September 24, 2019 23:14

Test GH actions to build docs

5aa514e

c24t force-pushed the c24t-patch-1 branch from f0c8948 to 5aa514e Compare September 24, 2019 23:16

Use JamesIves/github-pages-deploy-action

c8d4d97

c24t force-pushed the c24t-patch-1 branch 2 times, most recently from 4e67cf2 to 2274cd6 Compare September 24, 2019 23:50

Use personal access token

8abcfa6

Because of JamesIves/github-pages-deploy-action#5

c24t force-pushed the c24t-patch-1 branch from 2274cd6 to 8abcfa6 Compare September 24, 2019 23:53

Stop jekyll

640e36f

c24t added doc Documentation-related meta Related to repo itself, process, community, ... labels Sep 25, 2019

c24t added the WIP Work in progress label Sep 25, 2019

Build only on push to master, not on PRs

39adaf2

c24t removed the WIP Work in progress label Sep 25, 2019

c24t changed the title ~~Test GH actions to build docs~~ Build and host docs via github action Sep 25, 2019

This was referenced Sep 25, 2019

Add link to docs to README #170

Merged

Host docs on readthedocs.org #171

Closed

reyang approved these changes Sep 25, 2019

View reviewed changes

Oberon00 approved these changes Sep 25, 2019

View reviewed changes

c24t added 2 commits September 25, 2019 13:51

Use sphinx.ext.githubpages

2f3e42f

Install --upgrade tox on docs generation

4378744

c24t merged commit 81cd8d6 into master Sep 25, 2019

c24t deleted the c24t-patch-1 branch September 25, 2019 21:41

c24t mentioned this pull request Oct 28, 2019

Publish to PyPI via github action #247

Merged

dgzlopes mentioned this pull request Jan 27, 2020

Rebuild docs only if source files change #380

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Build and host docs via github action #167

Build and host docs via github action #167

c24t commented Sep 24, 2019 •

edited

Loading

Oberon00 left a comment

Oberon00 Sep 25, 2019

c24t Sep 25, 2019

Oberon00 Sep 25, 2019

c24t Sep 25, 2019

Oberon00 Sep 25, 2019 •

edited

Loading

c24t Sep 25, 2019

Build and host docs via github action #167

Build and host docs via github action #167

Conversation

c24t commented Sep 24, 2019 • edited Loading

Oberon00 left a comment

Choose a reason for hiding this comment

Oberon00 Sep 25, 2019

Choose a reason for hiding this comment

c24t Sep 25, 2019

Choose a reason for hiding this comment

Oberon00 Sep 25, 2019

Choose a reason for hiding this comment

c24t Sep 25, 2019

Choose a reason for hiding this comment

Oberon00 Sep 25, 2019 • edited Loading

Choose a reason for hiding this comment

c24t Sep 25, 2019

Choose a reason for hiding this comment

c24t commented Sep 24, 2019 •

edited

Loading

Oberon00 Sep 25, 2019 •

edited

Loading