From fdb6a44245249a50b5c95cdf0d8d13ecddfe5726 Mon Sep 17 00:00:00 2001 From: Aldo Cortesi Date: Wed, 12 Oct 2016 10:57:05 +1300 Subject: docs: cleanups improvements and fighting sphinx - Hide links to internal code listings, and link to github instead - Improve formatting of code/example captions - Fix outdated documentation of command-line options - Complete documentation of all events + improved formatting - tcp_open -> tcp_start, tcp_close -> tcp_end to reduce confusion --- docs/conf.py | 45 ++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 44 insertions(+), 1 deletion(-) (limited to 'docs/conf.py') diff --git a/docs/conf.py b/docs/conf.py index 54a353ac..76dc83d4 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -1,11 +1,16 @@ import sys import os +import importlib +import inspect sys.path.insert(0, os.path.abspath('..')) import netlib.version + extensions = [ 'sphinx.ext.autodoc', 'sphinx.ext.doctest', + 'sphinx.ext.extlinks', + 'sphinx.ext.linkcode', 'sphinx.ext.viewcode', 'sphinx.ext.napoleon', 'sphinxcontrib.documentedlist' @@ -156,7 +161,7 @@ html_static_path = ['_static'] #html_split_index = False # If true, links to the reST sources are added to the pages. -#html_show_sourcelink = True +html_show_sourcelink = False # If true, "Created using Sphinx" is shown in the HTML footer. Default is True. #html_show_sphinx = True @@ -189,5 +194,43 @@ html_static_path = ['_static'] # Output file base name for HTML help builder. htmlhelp_basename = 'mitmproxydoc' + +# FIXME: change master to dynamic version before release +extlinks = dict( + src = ('https://github.com/mitmproxy/mitmproxy/blob/master/%s', '') +) + + +MODULE = "/mitmproxy/" + +def linkcode_resolve(domain, info): + if domain != 'py': + return None + module, fullname = info['module'], info['fullname'] + # TODO: attributes/properties don't have modules, maybe try to look + # them up based on their cached host object? + if not module: + return None + obj = importlib.import_module(module) + for item in fullname.split('.'): + obj = getattr(obj, item, None) + if obj is None: + return None + try: + obj = getattr(obj, '_orig') + except AttributeError: + pass + try: + obj_source_path = inspect.getsourcefile(obj) + _, line = inspect.getsourcelines(obj) + except (TypeError, IOError): + # obj doesn't have a module, or something + return None + off = obj_source_path.rfind(MODULE) + mpath = obj_source_path[off + len(MODULE):] + print(obj_source_path, mpath) + return "https://github.com/mitmproxy/mitmproxy/blob/master/%s" % mpath + + def setup(app): app.add_stylesheet('theme_overrides.css') -- cgit v1.2.3 From 61040a7bcd46c057e34fe4671ef20b9111649e74 Mon Sep 17 00:00:00 2001 From: Aldo Cortesi Date: Fri, 14 Oct 2016 12:18:56 +1300 Subject: docs: improve external source links, tweak code docs --- docs/conf.py | 29 ++++++++++++++--------------- 1 file changed, 14 insertions(+), 15 deletions(-) (limited to 'docs/conf.py') diff --git a/docs/conf.py b/docs/conf.py index 76dc83d4..ef5f0556 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -195,20 +195,19 @@ html_show_sourcelink = False htmlhelp_basename = 'mitmproxydoc' +SRCBASE = "https://github.com/mitmproxy/mitmproxy/blob/master" + + # FIXME: change master to dynamic version before release extlinks = dict( - src = ('https://github.com/mitmproxy/mitmproxy/blob/master/%s', '') + src = (SRCBASE + r"/%s", '') ) -MODULE = "/mitmproxy/" - def linkcode_resolve(domain, info): if domain != 'py': return None module, fullname = info['module'], info['fullname'] - # TODO: attributes/properties don't have modules, maybe try to look - # them up based on their cached host object? if not module: return None obj = importlib.import_module(module) @@ -217,19 +216,19 @@ def linkcode_resolve(domain, info): if obj is None: return None try: - obj = getattr(obj, '_orig') - except AttributeError: - pass - try: - obj_source_path = inspect.getsourcefile(obj) + spath = inspect.getsourcefile(obj) _, line = inspect.getsourcelines(obj) except (TypeError, IOError): - # obj doesn't have a module, or something return None - off = obj_source_path.rfind(MODULE) - mpath = obj_source_path[off + len(MODULE):] - print(obj_source_path, mpath) - return "https://github.com/mitmproxy/mitmproxy/blob/master/%s" % mpath + if spath.rfind("netlib") > -1: + off = spath.rfind("netlib") + mpath = spath[off:] + elif spath.rfind("mitmproxy") > -1: + off = spath.rfind("mitmproxy") + mpath = spath[off:] + else: + return None + return SRCBASE + "/%s#L%s" % (mpath, line) def setup(app): -- cgit v1.2.3 From 072fff90f119375395a9b1b2fbef9667a46f7236 Mon Sep 17 00:00:00 2001 From: Maximilian Hils Date: Sat, 15 Oct 2016 18:00:21 -0700 Subject: docs: link to correct tag --- docs/conf.py | 21 ++++++++++++++++----- 1 file changed, 16 insertions(+), 5 deletions(-) (limited to 'docs/conf.py') diff --git a/docs/conf.py b/docs/conf.py index ef5f0556..e1cbc497 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -1,7 +1,9 @@ -import sys -import os import importlib import inspect +import os +import subprocess +import sys + sys.path.insert(0, os.path.abspath('..')) import netlib.version @@ -194,11 +196,20 @@ html_show_sourcelink = False # Output file base name for HTML help builder. htmlhelp_basename = 'mitmproxydoc' +last_tag, tag_dist, commit = ( + subprocess.check_output(["git", "describe", "--tags", "--long"]) + .decode() + .strip() + .rsplit("-", 2) +) +tag_dist = int(tag_dist) +if tag_dist == 0: + tag = last_tag +else: + tag = "master" -SRCBASE = "https://github.com/mitmproxy/mitmproxy/blob/master" - +SRCBASE = "https://github.com/mitmproxy/mitmproxy/blob/{}".format(tag) -# FIXME: change master to dynamic version before release extlinks = dict( src = (SRCBASE + r"/%s", '') ) -- cgit v1.2.3