Support doc shortcode (via #2170)

Signed-off-by: Chris Warrick <kwpolska@gmail.com>
getnikola · Jul 13, 2016 · 78ad75c · 78ad75c
1 parent 451c51f
commit 78ad75c
Show file tree

Hide file tree

Showing 3 changed files with 50 additions and 14 deletions.
diff --git a/CHANGES.txt b/CHANGES.txt
@@ -4,10 +4,12 @@ New in master
 Features
 --------
 
-* Added Albanian translation by Vango Stavro
+* Support ``doc`` shortcode (equivalent to reST ``doc`` role — part of
+  Issue #2170)
+* Albanian translation by Vango Stavro
 * Added ``post-(type)`` class to ``story.tmpl`` (uses the ``type``
   meta field, defaults to ``post-text`` — same behavior as posts)
-* Added ``compiled`` signal after post is compiled (Issue #2369)
+* New ``compiled`` signal after post is compiled (Issue #2369)
 
 Bugfixes
 --------

diff --git a/docs/manual.txt b/docs/manual.txt
@@ -863,6 +863,14 @@ Example of a paired shortcode (note that we don't have a highlight shortcode yet
 Built-in shortcodes
 ~~~~~~~~~~~~~~~~~~~
 
+doc
+    Will link to a document in the page, see `Doc directive for details
+    <#doc>`__. Example:
+
+    .. code:: restructuredtext
+
+       {{% raw %}}Take a look at {{% doc %}}my other post <creating-a-theme>{{% /doc %}} about theme creating.{{% /raw %}}
+
 post-list
     Will show a list of posts, see the `Post List directive for details <#post-list>`__
 

diff --git a/nikola/plugins/compile/rest/doc.py b/nikola/plugins/compile/rest/doc.py
@@ -29,7 +29,7 @@
 from docutils import nodes
 from docutils.parsers.rst import roles
 
-from nikola.utils import split_explicit_title
+from nikola.utils import split_explicit_title, LOGGER
 from nikola.plugin_categories import RestExtension
 
 
@@ -42,12 +42,12 @@ def set_site(self, site):
         """Set Nikola site."""
         self.site = site
         roles.register_canonical_role('doc', doc_role)
+        self.site.register_shortcode('doc', doc_shortcode)
         doc_role.site = site
         return super(Plugin, self).set_site(site)
 
 
-def doc_role(name, rawtext, text, lineno, inliner,
-             options={}, content=[]):
+def _doc_link(rawtext, text, options={}, content=[]):
     """Handle the doc role."""
     # split link's text and post's slug in role content
     has_explicit_title, title, slug = split_explicit_title(text)
@@ -66,22 +66,48 @@ def doc_role(name, rawtext, text, lineno, inliner,
         if post is None:
             raise ValueError
     except ValueError:
+        return False, False, None, None, None
+
+    if not has_explicit_title:
+        # use post's title as link's text
+        title = post.title()
+    permalink = post.permalink()
+
+    return True, twin_slugs, title, permalink, slug
+
+
+def doc_role(name, rawtext, text, lineno, inliner, options={}, content=[]):
+    """Handle the doc role."""
+    success, twin_slugs, title, permalink, slug = _doc_link(rawtext, text, options, content)
+    if success:
+        if twin_slugs:
+            inliner.reporter.warning(
+                'More than one post with the same slug. Using "{0}"'.format(permalink))
+            LOGGER.warn(
+                'More than one post with the same slug. Using "{0}" for doc role'.format(permalink))
+        node = make_link_node(rawtext, title, permalink, options)
+        return [node], []
+    else:
         msg = inliner.reporter.error(
             '"{0}" slug doesn\'t exist.'.format(slug),
             line=lineno)
         prb = inliner.problematic(rawtext, rawtext, msg)
         return [prb], [msg]
 
-    if not has_explicit_title:
-        # use post's title as link's text
-        title = post.title()
-    permalink = post.permalink()
-    if twin_slugs:
-        msg = inliner.reporter.warning(
-            'More than one post with the same slug. Using "{0}"'.format(permalink))
 
-    node = make_link_node(rawtext, title, permalink, options)
-    return [node], []
+def doc_shortcode(*args, **kwargs):
+    """Implement the doc shortcode."""
+    text = kwargs['data']
+    success, twin_slugs, title, permalink, slug = _doc_link(text, text, LOGGER)
+    if success:
+        if twin_slugs:
+            LOGGER.warn(
+                'More than one post with the same slug. Using "{0}" for doc shortcode'.format(permalink))
+        return '<a href="{0}">{1}</a>'.format(permalink, title)
+    else:
+        LOGGER.error(
+            '"{0}" slug doesn\'t exist.'.format(slug))
+        return '<span class="error text-error" style="color: red;">Invalid link: {0}</span>'.format(text)
 
 
 def make_link_node(rawtext, text, url, options):