From 24aa4a4bdc997b9df58d46ccca93733e5f31f1c3 Mon Sep 17 00:00:00 2001 From: Jean Baptiste Favre Date: Wed, 4 Jan 2017 13:38:25 +0100 Subject: [PATCH 1/3] Fix documentation build for docutils 0.13.1 (1/2) * Remove docutils internal Inliner monkey patching * Add new role for :ts:jira: in traffic_server Sphinx extension * Add new role for :ts:github: in traffic_server Sphinx extension --- doc/conf.py | 43 ++---------- doc/ext/traffic-server.py | 135 +++++++++++++++++++++++++++++++++++--- 2 files changed, 132 insertions(+), 46 deletions(-) diff --git a/doc/conf.py b/doc/conf.py index 8ee27b891ff..760570c7821 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -166,44 +166,9 @@ nitpicky=1 # Autolink issue references - -from docutils import nodes -from docutils.parsers.rst import states -from docutils.utils import unescape - -# Customize parser.inliner in the only way that Sphinx supports. -# docutils.parsers.rst.Parser takes an instance of states.Inliner or a -# subclass but Sphinx initializes it from -# SphinxStandaloneReader.set_parser('restructuredtext') which is called -# from Publisher.set_components() and initializes the parser without -# arguments. - -BaseInliner = states.Inliner -class Inliner(BaseInliner): - def __init__(self): - BaseInliner.__init__(self) - - issue_pattern = re.compile(u''' - {start_string_prefix} - TS-\d+ - {end_string_suffix}'''.format( - start_string_prefix=self.start_string_prefix, - end_string_suffix=self.end_string_suffix), - re.VERBOSE | re.UNICODE) - - self.implicit_dispatch.append((issue_pattern, self.issue_reference)) - - def issue_reference(self, match, lineno): - text = match.group(0) - - rawsource = unescape(text, True) - text = unescape(text, False) - - refuri = 'https://issues.apache.org/jira/browse/' + text - - return [nodes.reference(rawsource, text, refuri=refuri)] - -states.Inliner = Inliner +# moved into traffic_server Sphinx extension +trafficserver_jira_url='https://issues.apache.org/jira/browse/' +trafficserver_github_url='https://github.com/apache/trafficserver/issues/' # -- Options for HTML output --------------------------------------------------- @@ -352,6 +317,8 @@ def issue_reference(self, match, lineno): # documents and includes the same brief description in both the HTML # and manual page outputs. +from docutils import nodes +from docutils.utils import unescape from docutils.transforms import frontmatter from sphinx.writers import manpage diff --git a/doc/ext/traffic-server.py b/doc/ext/traffic-server.py index c11a20db8fa..bdfc32158ba 100644 --- a/doc/ext/traffic-server.py +++ b/doc/ext/traffic-server.py @@ -26,7 +26,8 @@ :license: Apache """ -from docutils import nodes +from docutils import nodes, utils +from docutils.parsers.rst.roles import set_classes from docutils.parsers import rst from docutils.parsers.rst import directives from sphinx.domains import Domain, ObjType, std @@ -34,6 +35,102 @@ from sphinx.locale import l_, _ import sphinx +# Autolink for Trafficserver issues +# Moved from doc/conf.py, now integrated into TS domain +# +# Two types of issues supported: +# * Jira: for archive purpose only (after the Jira to Github move) +# * Github: for new issues (after the Jira to Github move) +# +# Syntax: +# :ts:jira:`XXXX` where XXXX is the issue number +# :ts:github:`XXXX` where XXXX is the issue number +# +# Output +# * Prefix issue number with 'TS-' +# * Render HTML link: +# - either to https://issues.apache.org/jira/browse/TS-XXXX +# - or to https://github.com/apache/trafficserver/issues/XXXX + +def ts_jira_role(name, rawtext, issue_num, lineno, inliner, options={}, content=[]): + """Link to a Trafficserver Jira issue. + + Returns 2 part tuple containing list of nodes to insert into the + document and a list of system messages. Both are allowed to be + empty. + + :param name: The role name used in the document. + :param rawtext: The entire markup snippet, with role. + :param issue_num: The issue number marked with the role. + :param lineno: The line number where rawtext appears in the input. + :param inliner: The inliner instance that called us. + :param options: Directive options for customization. + :param content: The directive content for customization. + """ + app = inliner.document.settings.env.app + try: + base_url = app.config.trafficserver_jira_url + if not base_url: + raise AttributeError + except AttributeError, err: + raise ValueError('trafficserver_jira_url configuration values not set (%s)' % str(err)) + # + issue_prefix = 'TS-' + node = make_link_node(rawtext, app, base_url, issue_prefix, issue_num, options) + return [node], [] + +def ts_github_role(name, rawtext, issue_num, lineno, inliner, options={}, content=[]): + """Link to a Trafficserver Github issue. + + Returns 2 part tuple containing list of nodes to insert into the + document and a list of system messages. Both are allowed to be + empty. + + :param name: The role name used in the document. + :param rawtext: The entire markup snippet, with role. + :param text: The text marked with the role. + :param lineno: The line number where rawtext appears in the input. + :param inliner: The inliner instance that called us. + :param options: Directive options for customization. + :param content: The directive content for customization. + """ + app = inliner.document.settings.env.app + try: + base_url = app.config.trafficserver_github_url + if not base_url: + raise AttributeError + except AttributeError, err: + raise ValueError('trafficserver_github_url configuration values not set (%s)' % str(err)) + # + issue_prefix = '' + node = make_link_node(rawtext, app, base_url, issue_prefix, issue_num, options) + return [node], [] + +def make_link_node(rawtext, app, base_url, issue_prefix, issue_num, options): + """Create a link to a Apache Jira resource. + + :param rawtext: Text being replaced with link node. + :param app: Sphinx application context + :param type: Link type ('jira' or 'github') + :param slug: ID of the thing to link to + :param options: Options dictionary passed to role func. + """ + # + try: + issue_num_int = int(issue_num) + if issue_num_int <= 0: + raise ValueError + except ValueError: + raise ValueError('Trafficserver issue number must be a number greater than or equal to 1; ' + '"%s" is invalid.' % text, line=lineno) + # + base_url = base_url + issue_prefix + '{0}' + ref = base_url.format(issue_num) + set_classes(options) + node = nodes.reference(rawtext, issue_prefix + issue_num, refuri=ref, + **options) + return node + class TSConfVar(std.Target): """ Description of a traffic server configuration variable. @@ -273,6 +370,10 @@ class TSStatRef(XRefRole): def process_link(self, env, ref_node, explicit_title_p, title, target): return title, target +class TSIssueRef(XRefRole): + def process_link(self, env, ref_node, explicit_title_p, title, target): + return 'TS-' + title, 'https://issues.apache.org/jira/browse/TS-' + target + class TrafficServerDomain(Domain): """ Apache Traffic Server Documentation. @@ -284,7 +385,8 @@ class TrafficServerDomain(Domain): object_types = { 'cv': ObjType(l_('configuration variable'), 'cv'), - 'stat': ObjType(l_('statistic'), 'stat') + 'stat': ObjType(l_('statistic'), 'stat'), + 'jira': ObjType(l_('jira'), 'jira') } directives = { @@ -294,17 +396,21 @@ class TrafficServerDomain(Domain): roles = { 'cv' : TSConfVarRef(), - 'stat' : TSStatRef() + 'stat' : TSStatRef(), + 'jira' : ts_jira_role, + 'github' : ts_github_role } initial_data = { 'cv' : {}, # full name -> docname - 'stat' : {} + 'stat' : {}, + 'issue' : {} } dangling_warnings = { 'cv' : "No definition found for configuration variable '%(target)s'", - 'stat' : "No definition found for statistic '%(target)s'" + 'stat' : "No definition found for statistic '%(target)s'", + 'issue' : "No definition found for issue '%(target)s'" } def clear_doc(self, docname): @@ -316,6 +422,10 @@ def clear_doc(self, docname): for var, doc in stat_list.items(): if doc == docname: del stat_list[var] + issue_list = self.data['issue'] + for var, doc in issue_list.items(): + if doc == docname: + del issue_list[var] def find_doc(self, key, obj_type): zret = None @@ -324,6 +434,8 @@ def find_doc(self, key, obj_type): obj_list = self.data['cv'] elif obj_type == 'stat' : obj_list = self.data['stat'] + elif obj_type == 'issue' : + obj_list = self.data['issue'] else: obj_list = None @@ -333,15 +445,20 @@ def find_doc(self, key, obj_type): return zret def resolve_xref(self, env, src_doc, builder, obj_type, target, node, cont_node): - dst_doc = self.find_doc(target, obj_type) - if (dst_doc): - return sphinx.util.nodes.make_refnode(builder, src_doc, dst_doc, nodes.make_id(target), cont_node, 'records.config') + if obj_type == 'issue': + return sphinx.util.nodes.make_refnode(builder, src_doc, src_doc, nodes.make_id(target), cont_node, None) + else: + dst_doc = self.find_doc(target, obj_type) + if (dst_doc): + return sphinx.util.nodes.make_refnode(builder, src_doc, dst_doc, nodes.make_id(target), cont_node, 'records.config') def get_objects(self): for var, doc in self.data['cv'].iteritems(): yield var, var, 'cv', doc, var, 1 for var, doc in self.data['stat'].iteritems(): yield var, var, 'stat', doc, var, 1 + for var, doc in self.data['issue'].iteritems(): + yield var, var, 'issue', doc, var, 1 # These types are ignored as missing references for the C++ domain. # We really need to do better with this. Editing this file for each of @@ -383,6 +500,8 @@ def setup(app): rst.roles.register_generic_role('const', nodes.literal) app.add_domain(TrafficServerDomain) + app.add_config_value('trafficserver_jira_url', None, 'env') + app.add_config_value('trafficserver_github_url', None, 'env') # Types that we want the C domain to consider built in for word in EXTERNAL_TYPES: From 4478366fde3c6f3b7df0c124703b2e296c622503 Mon Sep 17 00:00:00 2001 From: Jean Baptiste Favre Date: Wed, 4 Jan 2017 13:40:14 +0100 Subject: [PATCH 2/3] Fix documentation build for docutils 0.13.1 (2/2) Update documentation to move current TS-XXXX issues to :ts:jira: syntax --- doc/admin-guide/configuration/cache-basics.en.rst | 2 +- doc/admin-guide/files/records.config.en.rst | 2 +- .../api/functions/TSHttpTxnClientPacketMarkSet.en.rst | 2 +- .../api/functions/TSHttpTxnClientPacketTosSet.en.rst | 2 +- .../api/functions/TSHttpTxnServerPacketMarkSet.en.rst | 2 +- .../api/functions/TSHttpTxnServerPacketTosSet.en.rst | 2 +- doc/developer-guide/api/functions/TSLifecycleHookAdd.en.rst | 2 +- doc/developer-guide/architecture/architecture.en.rst | 4 ++-- doc/developer-guide/architecture/consistency.en.rst | 2 +- 9 files changed, 10 insertions(+), 10 deletions(-) diff --git a/doc/admin-guide/configuration/cache-basics.en.rst b/doc/admin-guide/configuration/cache-basics.en.rst index 7351d1e0a88..497edcc4b91 100644 --- a/doc/admin-guide/configuration/cache-basics.en.rst +++ b/doc/admin-guide/configuration/cache-basics.en.rst @@ -683,7 +683,7 @@ cases the content will be buffered in ram while waiting to be sent to the client. This could potentially also happen for ``POST`` requests if the client connection is fast and the origin server connection slow. If very large objects are being used this can cause the memory usage of Traffic Server to become -`very large `_. +`very large :ts:jira:`1496``_. This problem can be ameliorated by controlling the amount of buffer space used by a transaction. A high water and low water mark are set in terms of bytes diff --git a/doc/admin-guide/files/records.config.en.rst b/doc/admin-guide/files/records.config.en.rst index 84d42cc4e27..58b2667a417 100644 --- a/doc/admin-guide/files/records.config.en.rst +++ b/doc/admin-guide/files/records.config.en.rst @@ -1091,7 +1091,7 @@ ip-resolve performed. The result is cached (if allowed otherwise). This option is vulnerable to cache poisoning if an incorrect ``Host`` header is specified, so this option should be used with extreme caution. See - bug TS-2954 for details. + bug :ts:jira:`2954` for details. ===== ====================================================================== If all of these conditions are met, then the origin server IP address is diff --git a/doc/developer-guide/api/functions/TSHttpTxnClientPacketMarkSet.en.rst b/doc/developer-guide/api/functions/TSHttpTxnClientPacketMarkSet.en.rst index 437f528b036..0272a271c55 100644 --- a/doc/developer-guide/api/functions/TSHttpTxnClientPacketMarkSet.en.rst +++ b/doc/developer-guide/api/functions/TSHttpTxnClientPacketMarkSet.en.rst @@ -41,4 +41,4 @@ See Also .. _Traffic Shaping: https://cwiki.apache.org/confluence/display/TS/Traffic+Shaping - :ts:cv:`proxy.config.net.sock_packet_mark_in` and TS-1090 + :ts:cv:`proxy.config.net.sock_packet_mark_in` and :ts:jira:`1090` diff --git a/doc/developer-guide/api/functions/TSHttpTxnClientPacketTosSet.en.rst b/doc/developer-guide/api/functions/TSHttpTxnClientPacketTosSet.en.rst index f1b694b9167..d5f1f3aa8b1 100644 --- a/doc/developer-guide/api/functions/TSHttpTxnClientPacketTosSet.en.rst +++ b/doc/developer-guide/api/functions/TSHttpTxnClientPacketTosSet.en.rst @@ -47,4 +47,4 @@ See Also .. _Traffic Shaping: https://cwiki.apache.org/confluence/display/TS/Traffic+Shaping - :ts:cv:`proxy.config.net.sock_packet_tos_in` and TS-1090 + :ts:cv:`proxy.config.net.sock_packet_tos_in` and :ts:jira:`1090` diff --git a/doc/developer-guide/api/functions/TSHttpTxnServerPacketMarkSet.en.rst b/doc/developer-guide/api/functions/TSHttpTxnServerPacketMarkSet.en.rst index af31dd84ed3..28c4c0dfe2d 100644 --- a/doc/developer-guide/api/functions/TSHttpTxnServerPacketMarkSet.en.rst +++ b/doc/developer-guide/api/functions/TSHttpTxnServerPacketMarkSet.en.rst @@ -45,4 +45,4 @@ See Also .. _Traffic Shaping: https://cwiki.apache.org/confluence/display/TS/Traffic+Shaping - :ts:cv:`proxy.config.net.sock_packet_mark_out` and TS-1090 + :ts:cv:`proxy.config.net.sock_packet_mark_out` and :ts:jira:`1090` diff --git a/doc/developer-guide/api/functions/TSHttpTxnServerPacketTosSet.en.rst b/doc/developer-guide/api/functions/TSHttpTxnServerPacketTosSet.en.rst index c412be1d08f..60a7f3da7d9 100644 --- a/doc/developer-guide/api/functions/TSHttpTxnServerPacketTosSet.en.rst +++ b/doc/developer-guide/api/functions/TSHttpTxnServerPacketTosSet.en.rst @@ -49,4 +49,4 @@ See Also .. _Traffic Shaping: https://cwiki.apache.org/confluence/display/TS/Traffic+Shaping - :ts:cv:`proxy.config.net.sock_packet_tos_out` and TS-1090 + :ts:cv:`proxy.config.net.sock_packet_tos_out` and :ts:jira:`1090` diff --git a/doc/developer-guide/api/functions/TSLifecycleHookAdd.en.rst b/doc/developer-guide/api/functions/TSLifecycleHookAdd.en.rst index 24ef96d158e..45c73139009 100644 --- a/doc/developer-guide/api/functions/TSLifecycleHookAdd.en.rst +++ b/doc/developer-guide/api/functions/TSLifecycleHookAdd.en.rst @@ -162,7 +162,7 @@ History ======= Lifecycle hooks were introduced to solve process initialization ordering issues -(TS-1487). Different API calls required different modules of |TS| to be +:ts:jira:`1487`. Different API calls required different modules of |TS| to be initialized for the call to work, but others did not work that late in initialization, which was problematic because all of them could effectively only be called from :func:`TSPluginInit` . The solution was to move diff --git a/doc/developer-guide/architecture/architecture.en.rst b/doc/developer-guide/architecture/architecture.en.rst index a38a1a56e02..497e1b54104 100644 --- a/doc/developer-guide/architecture/architecture.en.rst +++ b/doc/developer-guide/architecture/architecture.en.rst @@ -1147,12 +1147,12 @@ including the size of each stripe. .. [#store-disk-array] - `Work is under way `_ on + `Work is under way :ts:jira:`2020``_ on extending this to include objects that are in the memory cache. .. [#coalesced-spans] This linked list is mostly ignored in later processing, causing all but one file or directory storage units on the same device to be ignored. See - `TS-1869 `_. + :ts:jira:`1869`. diff --git a/doc/developer-guide/architecture/consistency.en.rst b/doc/developer-guide/architecture/consistency.en.rst index c5d5fafd20e..413cff54d2e 100644 --- a/doc/developer-guide/architecture/consistency.en.rst +++ b/doc/developer-guide/architecture/consistency.en.rst @@ -59,7 +59,7 @@ Volume Tagging ~~~~~~~~~~~~~~ Currently, :term:`cache volumes ` are allocated somewhat -arbitrarily from storage elements. `This enhancement `__ +arbitrarily from storage elements. `This enhancement :ts:jira:`1728``__ allows :file:`storage.config` to assign :term:`storage units ` to specific :term:`volumes ` although the volumes must still be listed in :file:`volume.config` in general and in particular to map domains to From 41ff99a25bb47cd383f0272b81a6c8e6969b95b7 Mon Sep 17 00:00:00 2001 From: Jean Baptiste Favre Date: Wed, 4 Jan 2017 14:08:04 +0100 Subject: [PATCH 3/3] Fix nested role (not supported) --- doc/admin-guide/configuration/cache-basics.en.rst | 2 +- doc/developer-guide/architecture/architecture.en.rst | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/doc/admin-guide/configuration/cache-basics.en.rst b/doc/admin-guide/configuration/cache-basics.en.rst index 497edcc4b91..8770e8ab45f 100644 --- a/doc/admin-guide/configuration/cache-basics.en.rst +++ b/doc/admin-guide/configuration/cache-basics.en.rst @@ -683,7 +683,7 @@ cases the content will be buffered in ram while waiting to be sent to the client. This could potentially also happen for ``POST`` requests if the client connection is fast and the origin server connection slow. If very large objects are being used this can cause the memory usage of Traffic Server to become -`very large :ts:jira:`1496``_. +very large (See issue :ts:jira:`1496`). This problem can be ameliorated by controlling the amount of buffer space used by a transaction. A high water and low water mark are set in terms of bytes diff --git a/doc/developer-guide/architecture/architecture.en.rst b/doc/developer-guide/architecture/architecture.en.rst index 497e1b54104..ec2e32c0f57 100644 --- a/doc/developer-guide/architecture/architecture.en.rst +++ b/doc/developer-guide/architecture/architecture.en.rst @@ -1147,8 +1147,8 @@ including the size of each stripe. .. [#store-disk-array] - `Work is under way :ts:jira:`2020``_ on - extending this to include objects that are in the memory cache. + Work is under way on extending this to include objects that are in the + memory cache. (See issue :ts:jira:`2020`) .. [#coalesced-spans]