doc: Basic sphinx docs

Makefile

@@ -14,7 +14,7 @@ help:
 	@false
 
 .venv:
-	virtualenv $(VENV_PATH)
+	virtualenv -ppython3 $(VENV_PATH)
 	$(VENV_PATH)/bin/pip install tox
 
 dist: .venv
@@ -48,12 +48,17 @@ lint: .venv
 
 .PHONY: lint
 
+apidocs-sphinx: .venv
+	@$(VENV_PATH)/bin/pip install --editable .
+	@$(VENV_PATH)/bin/pip install sphinx sphinx-rtd-theme 'git+https://github.com/untitaker/sphinx-autodoc-typehints@feat/type-hint-comments' typed_ast
+	@$(VENV_PATH)/bin/sphinx-build -b html docs/ docs/_build
+.PHONY: apidocs-sphinx
+
 apidocs: .venv
 	@$(VENV_PATH)/bin/pip install --editable .
 	@$(VENV_PATH)/bin/pip install pdoc==0.3.2 pygments
 	@$(VENV_PATH)/bin/pdoc --overwrite --html --html-dir build/apidocs sentry_sdk
 .PHONY: apidocs
-
 install-zeus-cli:
 	npm install -g @zeus-ci/cli
 .PHONY: install-zeus-cli

docs/.gitignore

@@ -0,0 +1 @@
+_build

docs/conf.py

@@ -0,0 +1,190 @@
+# -*- coding: utf-8 -*-
+
+import os
+import sys
+
+#
+# Configuration file for the Sphinx documentation builder.
+#
+# This file does only contain a selection of the most common options. For a
+# full list see the documentation:
+# http://www.sphinx-doc.org/en/master/config
+
+sys.path.insert(0, os.path.abspath(".."))
+
+# -- Project information -----------------------------------------------------
+
+project = u"sentry-python"
+copyright = u"2019, Sentry Team and Contributors"
+author = u"Sentry Team and Contributors"
+
+release = "0.9.5"
+version = ".".join(release.split(".")[:2])  # The short X.Y version.
+
+
+# -- General configuration ---------------------------------------------------
+
+# If your documentation needs a minimal Sphinx version, state it here.
+#
+# needs_sphinx = '1.0'
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+extensions = [
+    "sphinx.ext.autodoc",
+    "sphinx_autodoc_typehints",
+    "sphinx.ext.viewcode",
+    "sphinx.ext.githubpages",
+]
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ["_templates"]
+
+# The suffix(es) of source filenames.
+# You can specify multiple suffix as a list of string:
+#
+# source_suffix = ['.rst', '.md']
+source_suffix = ".rst"
+
+# The master toctree document.
+master_doc = "index"
+
+# The language for content autogenerated by Sphinx. Refer to documentation
+# for a list of supported languages.
+#
+# This is also used if you do content translation via gettext catalogs.
+# Usually you set "language" from the command line for these cases.
+language = None
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This pattern also affects html_static_path and html_extra_path.
+exclude_patterns = [u"_build", "Thumbs.db", ".DS_Store"]
+
+# The name of the Pygments (syntax highlighting) style to use.
+pygments_style = None
+
+
+# -- Options for HTML output -------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+#
+
+on_rtd = os.environ.get("READTHEDOCS", None) == "True"
+
+try:
+    import sphinx_rtd_theme
+
+    html_theme = "sphinx_rtd_theme"
+    html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
+except ImportError:
+    html_theme = "default"
+    if not on_rtd:
+        print("-" * 74)
+        print(
+            "Warning: sphinx-rtd-theme not installed, building with default " "theme."
+        )
+        print("-" * 74)
+
+# Theme options are theme-specific and customize the look and feel of a theme
+# further.  For a list of options available for each theme, see the
+# documentation.
+#
+# html_theme_options = {}
+
+# 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,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path = ["_static"]
+
+# Custom sidebar templates, must be a dictionary that maps document names
+# to template names.
+#
+# The default sidebars (for documents that don't match any pattern) are
+# defined by theme itself.  Builtin themes are using these templates by
+# default: ``['localtoc.html', 'relations.html', 'sourcelink.html',
+# 'searchbox.html']``.
+#
+# html_sidebars = {}
+
+
+# -- Options for HTMLHelp output ---------------------------------------------
+
+# Output file base name for HTML help builder.
+htmlhelp_basename = "sentry-pythondoc"
+
+
+# -- Options for LaTeX output ------------------------------------------------
+
+latex_elements = {
+    # The paper size ('letterpaper' or 'a4paper').
+    #
+    # 'papersize': 'letterpaper',
+    # The font size ('10pt', '11pt' or '12pt').
+    #
+    # 'pointsize': '10pt',
+    # Additional stuff for the LaTeX preamble.
+    #
+    # 'preamble': '',
+    # Latex figure (float) alignment
+    #
+    # 'figure_align': 'htbp',
+}
+
+# Grouping the document tree into LaTeX files. List of tuples
+# (source start file, target name, title,
+#  author, documentclass [howto, manual, or own class]).
+latex_documents = [
+    (
+        master_doc,
+        "sentry-python.tex",
+        u"sentry-python Documentation",
+        u"Sentry Team and Contributors",
+        "manual",
+    )
+]
+
+
+# -- Options for manual page output ------------------------------------------
+
+# One entry per manual page. List of tuples
+# (source start file, name, description, authors, manual section).
+man_pages = [(master_doc, "sentry-python", u"sentry-python Documentation", [author], 1)]
+
+
+# -- Options for Texinfo output ----------------------------------------------
+
+# Grouping the document tree into Texinfo files. List of tuples
+# (source start file, target name, title, author,
+#  dir menu entry, description, category)
+texinfo_documents = [
+    (
+        master_doc,
+        "sentry-python",
+        u"sentry-python Documentation",
+        author,
+        "sentry-python",
+        "One line description of project.",
+        "Miscellaneous",
+    )
+]
+
+
+# -- Options for Epub output -------------------------------------------------
+
+# Bibliographic Dublin Core info.
+epub_title = project
+
+# The unique identifier of the text. This can be a ISBN number
+# or the project homepage.
+#
+# epub_identifier = ''
+
+# A unique identification for the text.
+#
+# epub_uid = ''
+
+# A list of files that should not be packed into the epub file.
+epub_exclude_files = ["search.html"]

docs/index.rst

@@ -0,0 +1,10 @@
+=====================================
+sentry-python - Sentry SDK for Python
+=====================================
+
+This is the API documentation for `Sentry's Python SDK
+<https://sentry.io/for/python/>`_. For full documentation and other resources
+visit the `GitHub repository <https://github.com/getsentry/sentry-python>`_.
+
+.. automodule:: sentry_sdk
+    :members:

scripts/bump-version.sh

@@ -18,3 +18,4 @@ function replace() {
 
 replace "version=\"[0-9.]+\"" "version=\"$NEW_VERSION\"" ./setup.py
 replace "VERSION = \"[0-9.]+\"" "VERSION = \"$NEW_VERSION\"" ./sentry_sdk/consts.py
+replace "release = \"[0-9.]+\"" "release = \"$NEW_VERSION\"" ./docs/conf.py

sentry_sdk/__init__.py

@@ -1,27 +1,3 @@
-"""
-The Sentry SDK is the new-style SDK for [sentry.io](https://sentry.io/).  It implements
-the unified API that all modern SDKs follow for Python 2.7 and 3.5 or later.
-
-The user documentation can be found on [docs.sentry.io](https://docs.sentry.io/).
-
-## Quickstart
-
-The only thing to get going is to call `sentry_sdk.init()`.  When not passed any
-arguments the default options are used and the DSN is picked up from the `SENTRY_DSN`
-environment variable.  Otherwise the DSN can be passed with the `dsn` keyword
-or first argument.
-
-    import sentry_sdk
-    sentry_sdk.init()
-
-This initializes the default integrations which will automatically pick up any
-uncaught exceptions.  Additionally you can report arbitrary other exceptions:
-
-    try:
-        my_failing_function()
-    except Exception as e:
-        sentry_sdk.capture_exception(e)
-"""
 from sentry_sdk.hub import Hub, init
 from sentry_sdk.scope import Scope
 from sentry_sdk.transport import Transport, HttpTransport

sentry_sdk/api.py

@@ -4,7 +4,6 @@
 from sentry_sdk.hub import Hub
 from sentry_sdk.scope import Scope
 
-
 MYPY = False
 if MYPY:
     from typing import Any
@@ -40,42 +39,54 @@ def overload(x):
 def hubmethod(f):
     # type: (F) -> F
     f.__doc__ = "%s\n\n%s" % (
-        "Alias for `Hub.%s`" % f.__name__,
+        "Alias for :py:meth:`sentry_sdk.Hub.%s`" % f.__name__,
         inspect.getdoc(getattr(Hub, f.__name__)),
     )
     return f
 
 
 @hubmethod
-def capture_event(event, hint=None):
-    # type: (Event, Optional[Hint]) -> Optional[str]
+def capture_event(
+    event,  # type: Event
+    hint=None,  # type: Optional[Hint]
+):
+    # type: (...) -> Optional[str]
     hub = Hub.current
     if hub is not None:
         return hub.capture_event(event, hint)
     return None
 
 
 @hubmethod
-def capture_message(message, level=None):
-    # type: (str, Optional[str]) -> Optional[str]
+def capture_message(
+    message,  # type: str
+    level=None,  # type: Optional[str]
+):
+    # type: (...) -> Optional[str]
     hub = Hub.current
     if hub is not None:
         return hub.capture_message(message, level)
     return None
 
 
 @hubmethod
-def capture_exception(error=None):
-    # type: (Optional[BaseException]) -> Optional[str]
+def capture_exception(
+    error=None  # type: Optional[BaseException]
+):
+    # type: (...) -> Optional[str]
     hub = Hub.current
     if hub is not None:
         return hub.capture_exception(error)
     return None
 
 
 @hubmethod
-def add_breadcrumb(crumb=None, hint=None, **kwargs):
-    # type: (Optional[Breadcrumb], Optional[BreadcrumbHint], **Any) -> None
+def add_breadcrumb(
+    crumb=None,  # type: Optional[Breadcrumb]
+    hint=None,  # type: Optional[BreadcrumbHint]
+    **kwargs  # type: **Any
+):
+    # type: (...) -> None
     hub = Hub.current
     if hub is not None:
         return hub.add_breadcrumb(crumb, hint, **kwargs)
@@ -88,8 +99,10 @@ def configure_scope():
 
 
 @overload  # noqa
-def configure_scope(callback):
-    # type: (Callable[[Scope], None]) -> None
+def configure_scope(
+    callback  # type: Callable[[Scope], None]
+):
+    # type: (...) -> None
     pass
 
 
@@ -120,8 +133,10 @@ def push_scope():
 
 
 @overload  # noqa
-def push_scope(callback):
-    # type: (Callable[[Scope], None]) -> None
+def push_scope(
+    callback  # type: Callable[[Scope], None]
+):
+    # type: (...) -> None
     pass
 
 
@@ -146,8 +161,11 @@ def inner():
 
 
 @hubmethod
-def flush(timeout=None, callback=None):
-    # type: (Optional[float], Optional[Callable[[int, float], None]]) -> None
+def flush(
+    timeout=None,  # type: Optional[float]
+    callback=None,  # type: Optional[Callable[[int, float], None]]
+):
+    # type: (...) -> None
     hub = Hub.current
     if hub is not None:
         return hub.flush(timeout=timeout, callback=callback)

sentry_sdk/client.py

@@ -268,6 +268,7 @@ def __exit__(self, exc_type, exc_value, tb):
         self.close()
 
 
+MYPY = False
 if MYPY:
     # Make mypy, PyCharm and other static analyzers think `get_options` is a
     # type to have nicer autocompletion for params.