From 68eb42652715723ab40c6f5b681eea9cca7c03b9 Mon Sep 17 00:00:00 2001 From: Alessandro Comodi Date: Wed, 4 Sep 2019 13:01:23 +0200 Subject: [PATCH] addressed review comments Added prefix for code urls Changed Domain class name Signed-off-by: Alessandro Comodi --- README.md | 12 ++++++------ docs/conf.py | 11 +++++++---- docs/markdown_code_symlinks.py | 34 +++++++++++++++++++++++----------- 3 files changed, 36 insertions(+), 21 deletions(-) diff --git a/README.md b/README.md index c0f2f02c..68d1f6b0 100644 --- a/README.md +++ b/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 ](https://github.com/mithro) has graciously diff --git a/docs/conf.py b/docs/conf.py index aa8994b0..833cb06b 100644 --- a/docs/conf.py +++ b/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) diff --git a/docs/markdown_code_symlinks.py b/docs/markdown_code_symlinks.py index 5b746bda..f43bfcaa 100644 --- a/docs/markdown_code_symlinks.py +++ b/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