This is an automated email from the ASF dual-hosted git repository.
maskit pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/trafficserver.git
The following commit(s) were added to refs/heads/master by this push:
new a5dc160 Docs: Add macro to link to Github
a5dc160 is described below
commit a5dc16016c05369d627ea8b41dee43dcefe7caff
Author: Daniel Xu <[email protected]>
AuthorDate: Fri Apr 28 17:55:49 2017 -0500
Docs: Add macro to link to Github
This patch adds in a quality of life macro to link to Github from
reStructuredText documentation.
For example, to add a link to the logging header:
:ts:git:`proxy/logging/Log.h`
---
doc/developer-guide/documentation/ts-markup.en.rst | 19 +++++++++++
doc/ext/traffic-server.py | 37 ++++++++++++++++++++++
2 files changed, 56 insertions(+)
diff --git a/doc/developer-guide/documentation/ts-markup.en.rst
b/doc/developer-guide/documentation/ts-markup.en.rst
index 1f8b372..1a71eab 100644
--- a/doc/developer-guide/documentation/ts-markup.en.rst
+++ b/doc/developer-guide/documentation/ts-markup.en.rst
@@ -216,3 +216,22 @@ domain reference markup should be used::
References should not include the collection name, data type, or any other
components aside from the statistic name.
+
+Referencing source code
+-----------------------
+
+To reference source code from the documentation, use the following markup::
+
+ :ts:git:`path/to/source/file`
+
+This creates a link to Github. Sphinx does its best to pin the reference to the
+current release version of |ATS|.
+
+Avoid using hard links to Github as Github may be replaced with another host
+in the future.
+
+.. note::
+
+ Although adding the ability to point to a specific line number would not be
+ difficult, code shifts around too much and this feature would only cause
+ confusion to a downstream reader. This feature was deliberately omitted.
diff --git a/doc/ext/traffic-server.py b/doc/ext/traffic-server.py
index 1356f59..54c6443 100644
--- a/doc/ext/traffic-server.py
+++ b/doc/ext/traffic-server.py
@@ -34,6 +34,9 @@ from sphinx.roles import XRefRole
from sphinx.locale import l_, _
import sphinx
+import subprocess
+import re
+
class TSConfVar(std.Target):
"""
Description of a traffic server configuration variable.
@@ -371,6 +374,37 @@ def xref_cleanup(app, env, node, contnode):
return node
return;
+
+# get the branch this documentation is building for in X.X.x form
+with open('../configure.ac', 'r') as f:
+ contents = f.read()
+ match =
re.compile('m4_define\(\[TS_VERSION_S],\[(.*?)]\)').search(contents)
+ autoconf_version = '.'.join(match.group(1).split('.', 2)[:2] + ['x'])
+
+# get the current branch the local repository is on
+git_branch = subprocess.check_output(['git', 'rev-parse', '--abbrev-ref',
'HEAD'])
+
+def make_github_link(name, rawtext, text, lineno, inliner, options={},
content=[]):
+ """
+ This docutils role lets us link to source code via the handy :ts:git:
markup.
+ Link references are rooted at the top level source directory. All links
resolve
+ to GitHub.
+
+ Examples:
+
+ To link to proxy/Main.cc:
+
+ Hi, here is a link to the proxy entry point:
:ts:git:`proxy/Main.cc`.
+
+ To link to CONTRIBUTING.md:
+
+ If you want to contribute, take a look at
:ts:git:`CONTRIBUTING.md`.
+ """
+ url = 'https://github.com/apache/trafficserver/blob/{}/{}'
+ ref = autoconf_version if autoconf_version == git_branch else 'master'
+ node = nodes.reference(rawtext, text, refuri=url.format(ref, text),
**options)
+ return [node],[]
+
def setup(app):
app.add_crossref_type('configfile', 'file',
objname='Configuration file',
@@ -384,6 +418,9 @@ def setup(app):
app.add_domain(TrafficServerDomain)
+ # this lets us do :ts:git:`<file_path>` and link to the file on github
+ app.add_role_to_domain('ts', 'git', make_github_link)
+
# Types that we want the C domain to consider built in
for word in EXTERNAL_TYPES:
sphinx.domains.c.CObject.stopwords.add(word)
--
To stop receiving notification emails like this one, please contact
['"[email protected]" <[email protected]>'].
