addressed review comments

Added prefix for code urls
Changed Domain class name

Signed-off-by: Alessandro Comodi <acomodi@antmicro.com>

README.md

@@ -130,7 +130,7 @@ do.
 There are also "minitests" which are designs which can be viewed by a human in
 Vivado to better understand how to generate more useful designs.
 
-### [Experiments](https://github.com/SymbiFlow/prjxray/blob/master/experiments)
+### [Experiments](experiments)
 
 Experiments are like "minitests" except are only useful for a short period of
 time. Files are committed here to allow people to see how we are trying to
@@ -146,21 +146,21 @@ Fuzzers are the scripts which generate the large number of bitstream.
 They are called "fuzzers" because they follow an approach similar to the
 [idea of software testing through fuzzing](https://en.wikipedia.org/wiki/Fuzzing).
 
-### [Tools](https://github.com/SymbiFlow/prjxray/blob/master/tools) & [Libs](https://github.com/SymbiFlow/prjxray/blob/master/libs)
+### [Tools](tools) & [Libs](libs)
 
 Tools & libs are useful tools (and libraries) for converting the resulting
 bitstreams into various formats.
 
 Binaries in the tools directory are considered more mature and stable then
-those in the [utils](https://github.com/SymbiFlow/prjxray/blob/master/utils) directory and could be actively used in other
+those in the [utils](utils) directory and could be actively used in other
 projects.
 
-### [Utils](https://github.com/SymbiFlow/prjxray/blob/master/utils)
+### [Utils](utils)
 
 Utils are various tools which are still highly experimental. These tools should
 only be used inside this repository.
 
-### [Third Party](https://github.com/SymbiFlow/prjxray/blob/master/third_party)
+### [Third Party](third_party)
 
 Third party contains code not developed as part of Project X-Ray.
 
@@ -168,7 +168,7 @@ Third party contains code not developed as part of Project X-Ray.
 # Database
 
 Running the all fuzzers in order will produce a database which documents the
-bitstream format in the [database](https://github.com/SymbiFlow/prjxray/blob/master/database) directory.
+bitstream format in the [database](database) directory.
 
 As running all these fuzzers can take significant time,
 [Tim 'mithro' Ansell <me@mith.ro>](https://github.com/mithro) has graciously

docs/conf.py

@@ -24,7 +24,7 @@ import recommonmark
 import os
 import sys
 sys.path.insert(0, os.path.abspath('.'))
-from markdown_code_symlinks import LinkParser, PrjxrayDomain
+from markdown_code_symlinks import LinkParser, MarkdownSymlinksDomain
 
 # -- General configuration ------------------------------------------------
 
@@ -196,9 +196,12 @@ intersphinx_mapping = {'https://docs.python.org/': None}
 
 
 def setup(app):
-    PrjxrayDomain.find_links()
-    app.add_domain(PrjxrayDomain)
+    github_code_repo = 'https://github.com/SymbiFlow/prjxray/'
+
+    MarkdownSymlinksDomain.find_links()
+    MarkdownSymlinksDomain.add_github_repo(github_code_repo, 'blob/master/')
+    app.add_domain(MarkdownSymlinksDomain)
     app.add_config_value(
         'recommonmark_config', {
-            'github_code_repo': 'https://github.com/SymbiFlow/prjxray',
+            'github_code_repo': github_code_repo,
         }, True)

docs/markdown_code_symlinks.py

@@ -66,14 +66,14 @@ def relative(parent_dir, child_path):
     return os.path.relpath(child_path, start=parent_dir)
 
 
-class PrjxrayDomain(Domain):
+class MarkdownSymlinksDomain(Domain):
     """
     Extension of the Domain class to implement custom cross-reference links
     solve methodology
     """
 
-    name = 'prjxray'
-    label = 'Prjxray'
+    name = 'markdown_symlinks'
+    label = 'MarkdownSymlinks'
 
     roles = {
         'xref': XRefRole(),
@@ -87,6 +87,9 @@ class PrjxrayDomain(Domain):
         'code2docs': {},
     }
 
+    github_repo_url = ""
+    github_repo_branch = ""
+
     @classmethod
     def relative_code(cls, url):
         """Get a value relative to the code directory."""
@@ -162,8 +165,10 @@ Current Value: {}
         pprint.pprint(cls.mapping)
 
     @classmethod
-    def remove_extension(cls, path):
-        return filename
+    def add_github_repo(cls, github_repo_url, github_repo_branch):
+        """Initialize the github repository to update links correctly."""
+        cls.github_repo_url = github_repo_url
+        cls.github_repo_branch = github_repo_branch
 
     # Overriden method to solve the cross-reference link
     def resolve_xref(
@@ -174,11 +179,18 @@ Current Value: {}
             todocname = target
             targetid = ''
 
-        # Removing filename extension (e.g. contributing.md -> contributing)
-        todocname, _ = os.path.splitext(self.mapping['code2docs'][todocname])
+        if todocname not in self.mapping['code2docs']:
+            # Could be a link to a repository's code tree directory/file
+            todocname = '{}{}{}'.format(self.github_repo_url, self.github_repo_branch, todocname)
 
-        newnode = make_refnode(
-            builder, fromdocname, todocname, targetid, contnode[0])
+            newnode = nodes.reference('', '', internal=True, refuri=todocname)
+            newnode.append(contnode[0])
+        else:
+            # Removing filename extension (e.g. contributing.md -> contributing)
+            todocname, _ = os.path.splitext(self.mapping['code2docs'][todocname])
+
+            newnode = make_refnode(
+                builder, fromdocname, todocname, targetid, contnode[0])
 
         return newnode
 
@@ -186,7 +198,7 @@ Current Value: {}
             self, env, fromdocname, builder, target, node, contnode):
         res = self.resolve_xref(
             env, fromdocname, builder, 'xref', target, node, contnode)
-        return [('prjxray:xref', res)]
+        return [('markdown_symlinks:xref', res)]
 
 
 class LinkParser(parser.CommonMarkParser, object):
@@ -219,7 +231,7 @@ class LinkParser(parser.CommonMarkParser, object):
             wrap_node = addnodes.pending_xref(
                 reftarget=unquote(destination),
                 reftype='xref',
-                refdomain='prjxray',  # Added to enable cross-linking
+                refdomain='markdown_symlinks',  # Added to enable cross-linking
                 refexplicit=True,
                 refwarn=True)
             # TODO also not correct sourcepos