trafficserver-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From mas...@apache.org
Subject [trafficserver] branch master updated: Docs: Add macro to link to Github
Date Mon, 01 May 2017 02:40:29 GMT
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 <dxu@dxuuu.xyz>
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
['"commits@trafficserver.apache.org" <commits@trafficserver.apache.org>'].

Mime
View raw message