Skip to content

Commit 59c010d

Browse files
untitakeruntitaker
committed
doc: Basic sphinx docs
1 parent 0f9f725 commit 59c010d

File tree

12 files changed

+409
-114
lines changed

12 files changed

+409
-114
lines changed

‎Makefile

+7-2
Original file line numberDiff line numberDiff line change
@@ -14,7 +14,7 @@ help:
1414
@false
1515

1616
.venv:
17-
virtualenv $(VENV_PATH)
17+
virtualenv -ppython3 $(VENV_PATH)
1818
$(VENV_PATH)/bin/pip install tox
1919

2020
dist: .venv
@@ -48,12 +48,17 @@ lint: .venv
4848

4949
.PHONY: lint
5050

51+
apidocs-sphinx: .venv
52+
@$(VENV_PATH)/bin/pip install --editable .
53+
@$(VENV_PATH)/bin/pip install sphinx sphinx-rtd-theme 'git+https://github.com/untitaker/sphinx-autodoc-typehints@feat/type-hint-comments' typed_ast
54+
@$(VENV_PATH)/bin/sphinx-build -b html docs/ docs/_build
55+
.PHONY: apidocs-sphinx
56+
5157
apidocs: .venv
5258
@$(VENV_PATH)/bin/pip install --editable .
5359
@$(VENV_PATH)/bin/pip install pdoc==0.3.2 pygments
5460
@$(VENV_PATH)/bin/pdoc --overwrite --html --html-dir build/apidocs sentry_sdk
5561
.PHONY: apidocs
56-
5762
install-zeus-cli:
5863
npm install -g @zeus-ci/cli
5964
.PHONY: install-zeus-cli

‎docs/.gitignore

+1
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
_build

‎docs/conf.py

+190
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,190 @@
1+
# -*- coding: utf-8 -*-
2+
3+
import os
4+
import sys
5+
6+
#
7+
# Configuration file for the Sphinx documentation builder.
8+
#
9+
# This file does only contain a selection of the most common options. For a
10+
# full list see the documentation:
11+
# http://www.sphinx-doc.org/en/master/config
12+
13+
sys.path.insert(0, os.path.abspath(".."))
14+
15+
# -- Project information -----------------------------------------------------
16+
17+
project = u"sentry-python"
18+
copyright = u"2019, Sentry Team and Contributors"
19+
author = u"Sentry Team and Contributors"
20+
21+
release = "0.9.5"
22+
version = ".".join(release.split(".")[:2]) # The short X.Y version.
23+
24+
25+
# -- General configuration ---------------------------------------------------
26+
27+
# If your documentation needs a minimal Sphinx version, state it here.
28+
#
29+
# needs_sphinx = '1.0'
30+
31+
# Add any Sphinx extension module names here, as strings. They can be
32+
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
33+
# ones.
34+
extensions = [
35+
"sphinx.ext.autodoc",
36+
"sphinx_autodoc_typehints",
37+
"sphinx.ext.viewcode",
38+
"sphinx.ext.githubpages",
39+
]
40+
41+
# Add any paths that contain templates here, relative to this directory.
42+
templates_path = ["_templates"]
43+
44+
# The suffix(es) of source filenames.
45+
# You can specify multiple suffix as a list of string:
46+
#
47+
# source_suffix = ['.rst', '.md']
48+
source_suffix = ".rst"
49+
50+
# The master toctree document.
51+
master_doc = "index"
52+
53+
# The language for content autogenerated by Sphinx. Refer to documentation
54+
# for a list of supported languages.
55+
#
56+
# This is also used if you do content translation via gettext catalogs.
57+
# Usually you set "language" from the command line for these cases.
58+
language = None
59+
60+
# List of patterns, relative to source directory, that match files and
61+
# directories to ignore when looking for source files.
62+
# This pattern also affects html_static_path and html_extra_path.
63+
exclude_patterns = [u"_build", "Thumbs.db", ".DS_Store"]
64+
65+
# The name of the Pygments (syntax highlighting) style to use.
66+
pygments_style = None
67+
68+
69+
# -- Options for HTML output -------------------------------------------------
70+
71+
# The theme to use for HTML and HTML Help pages. See the documentation for
72+
# a list of builtin themes.
73+
#
74+
75+
on_rtd = os.environ.get("READTHEDOCS", None) == "True"
76+
77+
try:
78+
import sphinx_rtd_theme
79+
80+
html_theme = "sphinx_rtd_theme"
81+
html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
82+
except ImportError:
83+
html_theme = "default"
84+
if not on_rtd:
85+
print("-" * 74)
86+
print(
87+
"Warning: sphinx-rtd-theme not installed, building with default " "theme."
88+
)
89+
print("-" * 74)
90+
91+
# Theme options are theme-specific and customize the look and feel of a theme
92+
# further. For a list of options available for each theme, see the
93+
# documentation.
94+
#
95+
# html_theme_options = {}
96+
97+
# Add any paths that contain custom static files (such as style sheets) here,
98+
# relative to this directory. They are copied after the builtin static files,
99+
# so a file named "default.css" will overwrite the builtin "default.css".
100+
html_static_path = ["_static"]
101+
102+
# Custom sidebar templates, must be a dictionary that maps document names
103+
# to template names.
104+
#
105+
# The default sidebars (for documents that don't match any pattern) are
106+
# defined by theme itself. Builtin themes are using these templates by
107+
# default: ``['localtoc.html', 'relations.html', 'sourcelink.html',
108+
# 'searchbox.html']``.
109+
#
110+
# html_sidebars = {}
111+
112+
113+
# -- Options for HTMLHelp output ---------------------------------------------
114+
115+
# Output file base name for HTML help builder.
116+
htmlhelp_basename = "sentry-pythondoc"
117+
118+
119+
# -- Options for LaTeX output ------------------------------------------------
120+
121+
latex_elements = {
122+
# The paper size ('letterpaper' or 'a4paper').
123+
#
124+
# 'papersize': 'letterpaper',
125+
# The font size ('10pt', '11pt' or '12pt').
126+
#
127+
# 'pointsize': '10pt',
128+
# Additional stuff for the LaTeX preamble.
129+
#
130+
# 'preamble': '',
131+
# Latex figure (float) alignment
132+
#
133+
# 'figure_align': 'htbp',
134+
}
135+
136+
# Grouping the document tree into LaTeX files. List of tuples
137+
# (source start file, target name, title,
138+
# author, documentclass [howto, manual, or own class]).
139+
latex_documents = [
140+
(
141+
master_doc,
142+
"sentry-python.tex",
143+
u"sentry-python Documentation",
144+
u"Sentry Team and Contributors",
145+
"manual",
146+
)
147+
]
148+
149+
150+
# -- Options for manual page output ------------------------------------------
151+
152+
# One entry per manual page. List of tuples
153+
# (source start file, name, description, authors, manual section).
154+
man_pages = [(master_doc, "sentry-python", u"sentry-python Documentation", [author], 1)]
155+
156+
157+
# -- Options for Texinfo output ----------------------------------------------
158+
159+
# Grouping the document tree into Texinfo files. List of tuples
160+
# (source start file, target name, title, author,
161+
# dir menu entry, description, category)
162+
texinfo_documents = [
163+
(
164+
master_doc,
165+
"sentry-python",
166+
u"sentry-python Documentation",
167+
author,
168+
"sentry-python",
169+
"One line description of project.",
170+
"Miscellaneous",
171+
)
172+
]
173+
174+
175+
# -- Options for Epub output -------------------------------------------------
176+
177+
# Bibliographic Dublin Core info.
178+
epub_title = project
179+
180+
# The unique identifier of the text. This can be a ISBN number
181+
# or the project homepage.
182+
#
183+
# epub_identifier = ''
184+
185+
# A unique identification for the text.
186+
#
187+
# epub_uid = ''
188+
189+
# A list of files that should not be packed into the epub file.
190+
epub_exclude_files = ["search.html"]

‎docs/index.rst

+10
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
=====================================
2+
sentry-python - Sentry SDK for Python
3+
=====================================
4+
5+
This is the API documentation for `Sentry's Python SDK
6+
<https://sentry.io/for/python/>`_. For full documentation and other resources
7+
visit the `GitHub repository <https://github.com/getsentry/sentry-python>`_.
8+
9+
.. automodule:: sentry_sdk
10+
:members:

‎scripts/bump-version.sh

+1
Original file line numberDiff line numberDiff line change
@@ -18,3 +18,4 @@ function replace() {
1818

1919
replace "version=\"[0-9.]+\"" "version=\"$NEW_VERSION\"" ./setup.py
2020
replace "VERSION = \"[0-9.]+\"" "VERSION = \"$NEW_VERSION\"" ./sentry_sdk/consts.py
21+
replace "release = \"[0-9.]+\"" "release = \"$NEW_VERSION\"" ./docs/conf.py

‎sentry_sdk/__init__.py

-24
Original file line numberDiff line numberDiff line change
@@ -1,27 +1,3 @@
1-
"""
2-
The Sentry SDK is the new-style SDK for [sentry.io](https://sentry.io/). It implements
3-
the unified API that all modern SDKs follow for Python 2.7 and 3.5 or later.
4-
5-
The user documentation can be found on [docs.sentry.io](https://docs.sentry.io/).
6-
7-
## Quickstart
8-
9-
The only thing to get going is to call `sentry_sdk.init()`. When not passed any
10-
arguments the default options are used and the DSN is picked up from the `SENTRY_DSN`
11-
environment variable. Otherwise the DSN can be passed with the `dsn` keyword
12-
or first argument.
13-
14-
import sentry_sdk
15-
sentry_sdk.init()
16-
17-
This initializes the default integrations which will automatically pick up any
18-
uncaught exceptions. Additionally you can report arbitrary other exceptions:
19-
20-
try:
21-
my_failing_function()
22-
except Exception as e:
23-
sentry_sdk.capture_exception(e)
24-
"""
251
from sentry_sdk.hub import Hub, init
262
from sentry_sdk.scope import Scope
273
from sentry_sdk.transport import Transport, HttpTransport

‎sentry_sdk/api.py

+34-16
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,6 @@
44
from sentry_sdk.hub import Hub
55
from sentry_sdk.scope import Scope
66

7-
87
MYPY = False
98
if MYPY:
109
from typing import Any
@@ -40,42 +39,54 @@ def overload(x):
4039
def hubmethod(f):
4140
# type: (F) -> F
4241
f.__doc__ = "%s\n\n%s" % (
43-
"Alias for `Hub.%s`" % f.__name__,
42+
"Alias for :py:meth:`sentry_sdk.Hub.%s`" % f.__name__,
4443
inspect.getdoc(getattr(Hub, f.__name__)),
4544
)
4645
return f
4746

4847

4948
@hubmethod
50-
def capture_event(event, hint=None):
51-
# type: (Event, Optional[Hint]) -> Optional[str]
49+
def capture_event(
50+
event, # type: Event
51+
hint=None, # type: Optional[Hint]
52+
):
53+
# type: (...) -> Optional[str]
5254
hub = Hub.current
5355
if hub is not None:
5456
return hub.capture_event(event, hint)
5557
return None
5658

5759

5860
@hubmethod
59-
def capture_message(message, level=None):
60-
# type: (str, Optional[str]) -> Optional[str]
61+
def capture_message(
62+
message, # type: str
63+
level=None, # type: Optional[str]
64+
):
65+
# type: (...) -> Optional[str]
6166
hub = Hub.current
6267
if hub is not None:
6368
return hub.capture_message(message, level)
6469
return None
6570

6671

6772
@hubmethod
68-
def capture_exception(error=None):
69-
# type: (Optional[BaseException]) -> Optional[str]
73+
def capture_exception(
74+
error=None # type: Optional[BaseException]
75+
):
76+
# type: (...) -> Optional[str]
7077
hub = Hub.current
7178
if hub is not None:
7279
return hub.capture_exception(error)
7380
return None
7481

7582

7683
@hubmethod
77-
def add_breadcrumb(crumb=None, hint=None, **kwargs):
78-
# type: (Optional[Breadcrumb], Optional[BreadcrumbHint], **Any) -> None
84+
def add_breadcrumb(
85+
crumb=None, # type: Optional[Breadcrumb]
86+
hint=None, # type: Optional[BreadcrumbHint]
87+
**kwargs # type: **Any
88+
):
89+
# type: (...) -> None
7990
hub = Hub.current
8091
if hub is not None:
8192
return hub.add_breadcrumb(crumb, hint, **kwargs)
@@ -88,8 +99,10 @@ def configure_scope():
8899

89100

90101
@overload # noqa
91-
def configure_scope(callback):
92-
# type: (Callable[[Scope], None]) -> None
102+
def configure_scope(
103+
callback # type: Callable[[Scope], None]
104+
):
105+
# type: (...) -> None
93106
pass
94107

95108

@@ -120,8 +133,10 @@ def push_scope():
120133

121134

122135
@overload # noqa
123-
def push_scope(callback):
124-
# type: (Callable[[Scope], None]) -> None
136+
def push_scope(
137+
callback # type: Callable[[Scope], None]
138+
):
139+
# type: (...) -> None
125140
pass
126141

127142

@@ -146,8 +161,11 @@ def inner():
146161

147162

148163
@hubmethod
149-
def flush(timeout=None, callback=None):
150-
# type: (Optional[float], Optional[Callable[[int, float], None]]) -> None
164+
def flush(
165+
timeout=None, # type: Optional[float]
166+
callback=None, # type: Optional[Callable[[int, float], None]]
167+
):
168+
# type: (...) -> None
151169
hub = Hub.current
152170
if hub is not None:
153171
return hub.flush(timeout=timeout, callback=callback)

‎sentry_sdk/client.py

+1
Original file line numberDiff line numberDiff line change
@@ -268,6 +268,7 @@ def __exit__(self, exc_type, exc_value, tb):
268268
self.close()
269269

270270

271+
MYPY = False
271272
if MYPY:
272273
# Make mypy, PyCharm and other static analyzers think `get_options` is a
273274
# type to have nicer autocompletion for params.

0 commit comments

Comments
 (0)