add link to source code in docs (#4807)

* add link to source code in docs

* fix test

Author: epwalsh

.github/workflows/ci.yml

@@ -373,6 +373,16 @@ jobs:
       run: |
         pip freeze
 
+    - name: Prepare environment
+      run: |
+        if [[ $GITHUB_EVENT_NAME == 'release' ]]; then
+            echo "DOCS_FOLDER=${GITHUB_REF#refs/tags/}" >> $GITHUB_ENV;
+            echo "BASE_SOURCE_LINK=https://github.com/allenai/allennlp/blob/${GITHUB_REF#refs/tags/}/allennlp/" >> $GITHUB_ENV;
+        else
+            echo "DOCS_FOLDER=master" >> $GITHUB_ENV;
+            echo "BASE_SOURCE_LINK=https://github.com/allenai/allennlp/blob/master/allennlp/" >> $GITHUB_ENV;
+        fi
+
     - name: Build docs
       run: |
         ./scripts/build_docs.sh
@@ -384,15 +394,6 @@ jobs:
         git config --global user.name "ai2service"
         git config --global push.default simple
 
-    - name: Set target folders
-      if: github.event_name == 'release' || github.event_name == 'push'
-      run: |
-        if [[ $GITHUB_EVENT_NAME == 'release' ]]; then
-            echo "DOCS_FOLDER=${GITHUB_REF#refs/tags/}" >> $GITHUB_ENV;
-        else
-            echo "DOCS_FOLDER=master" >> $GITHUB_ENV;
-        fi
-
     - name: Stage docs
       if: github.event_name == 'release' || github.event_name == 'push'
       run: |

CHANGELOG.md

@@ -8,6 +8,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## Unreleased
 
+### Added
+
+- Added links to source code in docs.
+
 
 ## [v1.2.2](https://github.com/allenai/allennlp/releases/tag/v1.2.2) - 2020-11-17
 

docs/css/extra.css

@@ -7,3 +7,15 @@ h4 {
 h2, h3, h4 {
     color: #213744;
 }
+
+.alignleft {
+	float: left;
+}
+
+.alignright {
+	float: right;
+}
+
+a.sourcelink {
+    color: #888;
+}

scripts/py2md.py

@@ -29,6 +29,10 @@
 
 logging.basicConfig(level=logging.INFO)
 logger = logging.getLogger("py2md")
+BASE_MODULE = os.environ.get("BASE_MODULE", "allennlp")
+BASE_SOURCE_LINK = os.environ.get(
+    "BASE_SOURCE_LINK", "https://github.com/allenai/allennlp/blob/master/allennlp/"
+)
 
 
 class DocstringError(Exception):
@@ -247,7 +251,7 @@ def _transform_cross_references(self, line: str) -> str:
         Replace sphinx style crossreferences with markdown links.
         """
         for match, ty, name in self.CROSS_REF_RE.findall(line):
-            if name.startswith("allennlp."):
+            if name.startswith(f"{BASE_MODULE}."):
                 path = name.split(".")
                 if ty == "mod":
                     href = "/api/" + "/".join(path[1:])
@@ -396,20 +400,24 @@ def _format_classdef_signature(self, cls: Class) -> str:
 
     def _render_module_breadcrumbs(self, fp, mod: Module):
         submods = mod.name.split(".")
-        if submods[0] != "allennlp":
-            return
         breadcrumbs = []
         for i, submod_name in enumerate(submods):
             if i == 0:
-                title = f"*{submod_name}*"
+                title = f"<i>{submod_name}</i>"
             elif i == len(submods) - 1:
-                title = f"**.{submod_name}**"
+                title = f"<strong>.{submod_name}</strong>"
             else:
-                title = f"*.{submod_name}*"
-            #  href = "/api/" + "/".join(submods[1 : i + 1])
-            #  breadcrumbs.append(f"[{title}]({href})")
+                title = f"<i>.{submod_name}</i>"
             breadcrumbs.append(title)
-        fp.write("[ " + "".join(breadcrumbs) + " ]\n\n---\n\n")
+        "/".join(submods[1:])
+        source_link = BASE_SOURCE_LINK + "/".join(submods[1:]) + ".py"
+        fp.write(
+            "<div>\n"
+            ' <p class="alignleft">' + "".join(breadcrumbs) + "</p>\n"
+            f' <p class="alignright"><a class="sourcelink" href="{source_link}">[SOURCE]</a></p>\n'
+            "</div>\n"
+            '<div style="clear: both;"></div>\n\n---\n\n'
+        )
 
     def _render_object(self, fp, level, obj):
         if not isinstance(obj, Module) or self.render_module_header:

scripts/tests/py2md/basic_example_expected_output.md

@@ -1,3 +1,11 @@
+<div>
+ <p class="alignleft"><i>scripts</i><i>.tests</i><i>.py2md</i><strong>.basic_example</strong></p>
+ <p class="alignright"><a class="sourcelink" href="https://github.com/allenai/allennlp/blob/master/allennlp/tests/py2md/basic_example.py">[SOURCE]</a></p>
+</div>
+<div style="clear: both;"></div>
+
+---
+
 This is a docstring.
 
 And this is a multi-line line: [http://example.com](https://example.com/blah/blah/blah.html).