Add api documentation to the doc tree (#88)

liyanhui1228 · web-flow · commit 717fa49127c4 · 2017-11-29T15:48:27.000-08:00
diff --git a/.travis.yml b/.travis.yml
@@ -3,10 +3,10 @@ python:
   - '3.6'
 
 install:
-  - pip install --upgrade sphinx
+  - pip install --upgrade nox-automation
 
 script:
-  - ./scripts/update_docs.sh
+  - nox -s docs
   - touch docs/.nojekyll
 
 branches:
diff --git a/docs/conf.py b/docs/conf.py
@@ -97,7 +97,9 @@
 # further.  For a list of options available for each theme, see the
 # documentation.
 #
-# html_theme_options = {}
+html_theme_options = {
+    'sidebar_width': '260px',
+}
 
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
@@ -173,6 +175,3 @@
      author, 'OPENCENSUS', 'One line description of project.',
      'Miscellaneous'),
 ]
-
-
-
diff --git a/docs/trace/always_off_sampler.rst b/docs/trace/always_off_sampler.rst
@@ -0,0 +1,6 @@
+Sampler - AlwaysOffSampler
+==========================
+
+.. automodule:: opencensus.trace.samplers.always_off
+  :members:
+  :show-inheritance:
diff --git a/docs/trace/always_on_sampler.rst b/docs/trace/always_on_sampler.rst
@@ -0,0 +1,6 @@
+Sampler - AlwaysOnSampler
+=========================
+
+.. automodule:: opencensus.trace.samplers.always_on
+  :members:
+  :show-inheritance:
diff --git a/docs/trace/binary_format_propagation.rst b/docs/trace/binary_format_propagation.rst
@@ -0,0 +1,6 @@
+Propagator - BinaryFormatPropagator
+===================================
+
+.. automodule:: opencensus.trace.propagation.binary_format
+  :members:
+  :show-inheritance:
diff --git a/docs/trace/context_tracer.rst b/docs/trace/context_tracer.rst
@@ -0,0 +1,6 @@
+Context Tracer
+==============
+
+.. automodule:: opencensus.trace.tracer.context_tracer
+  :members:
+  :show-inheritance:
diff --git a/docs/trace/execution_context.rst b/docs/trace/execution_context.rst
@@ -0,0 +1,6 @@
+Execution Context
+=================
+
+.. automodule:: opencensus.trace.execution_context
+  :members:
+  :show-inheritance:
diff --git a/docs/trace/file_exporter.rst b/docs/trace/file_exporter.rst
@@ -0,0 +1,6 @@
+Exporter - File Exporter
+========================
+
+.. automodule:: opencensus.trace.exporters.file_exporter
+  :members:
+  :show-inheritance:
diff --git a/docs/trace/google_cloud_format_propagation.rst b/docs/trace/google_cloud_format_propagation.rst
@@ -0,0 +1,6 @@
+Propagator - GoogleCloudFormatPropagator
+========================================
+
+.. automodule:: opencensus.trace.propagation.google_cloud_format
+  :members:
+  :show-inheritance:
diff --git a/docs/trace/logging_exporter.rst b/docs/trace/logging_exporter.rst
@@ -0,0 +1,6 @@
+Exporter - Logging Exporter
+===========================
+
+.. automodule:: opencensus.trace.exporters.logging_exporter
+  :members:
+  :show-inheritance:
diff --git a/docs/trace/noop_tracer.rst b/docs/trace/noop_tracer.rst
@@ -0,0 +1,6 @@
+Noop Tracer
+===========
+
+.. automodule:: opencensus.trace.tracer.noop_tracer
+  :members:
+  :show-inheritance:
diff --git a/docs/trace/print_exporter.rst b/docs/trace/print_exporter.rst
@@ -0,0 +1,6 @@
+Exporter - Print Exporter
+=========================
+
+.. automodule:: opencensus.trace.exporters.print_exporter
+  :members:
+  :show-inheritance:
diff --git a/docs/trace/probability_sampler.rst b/docs/trace/probability_sampler.rst
@@ -0,0 +1,6 @@
+Sampler - ProbabilitySampler
+============================
+
+.. automodule:: opencensus.trace.samplers.probability
+  :members:
+  :show-inheritance:
diff --git a/docs/trace/request_tracer.rst b/docs/trace/request_tracer.rst
@@ -0,0 +1,6 @@
+Request Tracer
+==============
+
+.. automodule:: opencensus.trace.request_tracer
+  :members:
+  :show-inheritance:
diff --git a/docs/trace/span.rst b/docs/trace/span.rst
@@ -0,0 +1,6 @@
+Span
+====
+
+.. automodule:: opencensus.trace.span
+  :members:
+  :show-inheritance:
diff --git a/docs/trace/span_context.rst b/docs/trace/span_context.rst
@@ -0,0 +1,6 @@
+Span Context
+============
+
+.. automodule:: opencensus.trace.span_context
+  :members:
+  :show-inheritance:
diff --git a/docs/trace/stackdriver_exporter.rst b/docs/trace/stackdriver_exporter.rst
@@ -0,0 +1,6 @@
+Exporter - Stackdriver Exporter
+===============================
+
+.. automodule:: opencensus.trace.exporters.stackdriver_exporter
+  :members:
+  :show-inheritance:
diff --git a/docs/trace/text_format_propagation.rst b/docs/trace/text_format_propagation.rst
@@ -0,0 +1,6 @@
+Propagator - TextFormatPropagator
+=================================
+
+.. automodule:: opencensus.trace.propagation.text_format
+  :members:
+  :show-inheritance:
diff --git a/docs/trace/trace_context_http_header_format_propagation.rst b/docs/trace/trace_context_http_header_format_propagation.rst
@@ -0,0 +1,6 @@
+Propagator - TraceContextPropagator
+===================================
+
+.. automodule:: opencensus.trace.propagation.trace_context_http_header_format
+  :members:
+  :show-inheritance:
diff --git a/docs/trace/trace_options.rst b/docs/trace/trace_options.rst
@@ -0,0 +1,6 @@
+Trace Options
+=============
+
+.. automodule:: opencensus.trace.trace_options
+  :members:
+  :show-inheritance:
diff --git a/docs/trace/usage.html b/docs/trace/usage.html
diff --git a/docs/trace/usage.rst b/docs/trace/usage.rst
@@ -1,11 +1,29 @@
-OpenCensus for Python - A stats collection and distributed tracing framework
-============================================================================
-
-`Census`_ for Python. Census provides a framework to measure a server's resource
-usage and collect performance stats. This repository contains Python related
-utilities and supporting software needed by Census.
-
-.. _Census: https://github.com/census-instrumentation
+OpenCensus Trace for Python
+===========================
+
+.. toctree::
+  :maxdepth: 2
+  :hidden:
+
+  span
+  span_context
+  request_tracer
+  execution_context
+  trace_options
+  always_on_sampler
+  always_off_sampler
+  probability_sampler
+  print_exporter
+  logging_exporter
+  stackdriver_exporter
+  zipkin_exporter
+  file_exporter
+  binary_format_propagation
+  google_cloud_format_propagation
+  text_format_propagation
+  trace_context_http_header_format_propagation
+  noop_tracer
+  context_tracer
 
 Installation & basic usage
 --------------------------
diff --git a/docs/trace/zipkin_exporter.rst b/docs/trace/zipkin_exporter.rst
@@ -0,0 +1,6 @@
+Exporter - Zipkin Exporter
+==========================
+
+.. automodule:: opencensus.trace.exporters.zipkin_exporter
+  :members:
+  :show-inheritance:
diff --git a/scripts/update_docs.sh b/scripts/update_docs.sh
@@ -17,7 +17,6 @@ set -ev
 # Build docs
 function build_docs {
     rm -rf docs/build/
-    cp README.rst docs/trace/usage.rst
     make html
     return $?
 }
diff --git a/trace/opencensus/trace/exporters/file_exporter.py b/trace/opencensus/trace/exporters/file_exporter.py
@@ -30,7 +30,7 @@ class FileExporter(base.Exporter):
     :type transport: :class:`type`
     :param transport: Class for creating new transport objects. It should
                       extend from the base :class:`.Transport` type and
-                      implement :meth`.Transport.export`. Defaults to
+                      implement :meth:`.Transport.export`. Defaults to
                       :class:`.SyncTransport`. The other option is
                       :class:`.BackgroundThreadTransport`.
     """
diff --git a/trace/opencensus/trace/exporters/logging_exporter.py b/trace/opencensus/trace/exporters/logging_exporter.py
@@ -30,7 +30,7 @@ class LoggingExporter(base.Exporter):
     :type transport: :class:`type`
     :param transport: Class for creating new transport objects. It should
                       extend from the base :class:`.Transport` type and
-                      implement :meth`.Transport.export`. Defaults to
+                      implement :meth:`.Transport.export`. Defaults to
                       :class:`.SyncTransport`. The other option is
                       :class:`.BackgroundThreadTransport`.
 
diff --git a/trace/opencensus/trace/exporters/print_exporter.py b/trace/opencensus/trace/exporters/print_exporter.py
@@ -24,7 +24,7 @@ class PrintExporter(base.Exporter):
     :type transport: :class:`type`
     :param transport: Class for creating new transport objects. It should
                       extend from the base :class:`.Transport` type and
-                      implement :meth`.Transport.export`. Defaults to
+                      implement :meth:`.Transport.export`. Defaults to
                       :class:`.SyncTransport`. The other option is
                       :class:`.BackgroundThreadTransport`.
     """
diff --git a/trace/opencensus/trace/exporters/stackdriver_exporter.py b/trace/opencensus/trace/exporters/stackdriver_exporter.py
@@ -84,7 +84,7 @@ class StackdriverExporter(base.Exporter):
     :type transport: :class:`type`
     :param transport: Class for creating new transport objects. It should
                       extend from the base :class:`.Transport` type and
-                      implement :meth`.Transport.export`. Defaults to
+                      implement :meth:`.Transport.export`. Defaults to
                       :class:`.SyncTransport`. The other option is
                       :class:`.BackgroundThreadTransport`.
     """
diff --git a/trace/opencensus/trace/exporters/zipkin_exporter.py b/trace/opencensus/trace/exporters/zipkin_exporter.py
@@ -60,7 +60,7 @@ class ZipkinExporter(base.Exporter):
     :type transport: :class:`type`
     :param transport: Class for creating new transport objects. It should
                       extend from the base :class:`.Transport` type and
-                      implement :meth`.Transport.export`. Defaults to
+                      implement :meth:`.Transport.export`. Defaults to
                       :class:`.SyncTransport`. The other option is
                       :class:`.BackgroundThreadTransport`.
     """
diff --git a/trace/opencensus/trace/propagation/google_cloud_format.py b/trace/opencensus/trace/propagation/google_cloud_format.py
@@ -12,12 +12,6 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-"""This file is for converting the trace header in google cloud format and
-generate a SpanContext, or converting a SpanContext to a google cloud format
-header. Later we will add implementation for supporting other format like
-binary format and zipkin, opencensus format.
-"""
-
 import logging
 import re
 
@@ -31,7 +25,11 @@
 
 
 class GoogleCloudFormatPropagator(object):
-
+    """This class is for converting the trace header in google cloud format
+    and generate a SpanContext, or converting a SpanContext to a google cloud
+    format header. Later we will add implementation for supporting other
+    format like binary format and zipkin, opencensus format.
+    """
     def from_header(self, header):
         """Generate a SpanContext object using the trace context header.
         The value of enabled parsed from header is int. Need to convert to
diff --git a/trace/opencensus/trace/propagation/text_format.py b/trace/opencensus/trace/propagation/text_format.py
@@ -12,11 +12,6 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-"""This module provides the basic utilities for extracting the trace
-information from a carrier which is a dict to form a SpanContext. And
-generating a dict using the provided SpanContext.
-"""
-
 from opencensus.trace.span_context import SpanContext
 from opencensus.trace.trace_options import TraceOptions
 
@@ -29,7 +24,10 @@
 
 
 class TextFormatPropagator(object):
-
+    """This class provides the basic utilities for extracting the trace
+    information from a carrier which is a dict to form a SpanContext. And
+    generating a dict using the provided SpanContext.
+    """
     def from_carrier(self, carrier):
         """Generate a SpanContext object using the information in the carrier.
 
diff --git a/trace/opencensus/trace/propagation/trace_context_http_header_format.py b/trace/opencensus/trace/propagation/trace_context_http_header_format.py
@@ -24,6 +24,7 @@
 
 
 class TraceContextPropagator(object):
+    """Propagator for processing the trace context HTTP header format."""
 
     def from_header(self, header):
         """Generate a SpanContext object using the trace context header.
diff --git a/trace/opencensus/trace/samplers/always_off.py b/trace/opencensus/trace/samplers/always_off.py
@@ -16,6 +16,7 @@
 
 
 class AlwaysOffSampler(Sampler):
+    """Do not trace any requests."""
 
     def should_sample(self, trace_id):
         """Always return False because we don't want to sample."""
diff --git a/trace/opencensus/trace/samplers/always_on.py b/trace/opencensus/trace/samplers/always_on.py
@@ -16,7 +16,8 @@
 
 
 class AlwaysOnSampler(Sampler):
+    """Trace every request."""
 
     def should_sample(self, trace_id):
-        """Always return True because we want to sampler all requests."""
+        """Always return True because we want to sample all requests."""
         return True
diff --git a/trace/opencensus/trace/samplers/probability.py b/trace/opencensus/trace/samplers/probability.py
@@ -35,6 +35,15 @@ def __init__(self, rate=None):
         self.rate = rate
 
     def should_sample(self, trace_id):
+        """Make the sampling decision based on the lower 8 bytes of the trace
+        ID. If the value is less than the bound, return True, else False.
+
+        :type trace_id: str
+        :param trace_id: Trace ID of the current trace.
+
+        :rtype: bool
+        :returns: The sampling decision.
+        """
         lower_long = get_lower_long_from_trace_id(trace_id)
         bound = self.rate * MAX_VALUE
 
