From d0ab539f253b082aded91b2639e455fbb5104129 Mon Sep 17 00:00:00 2001 From: Alessandro Comodi Date: Mon, 2 Sep 2019 16:54:43 +0200 Subject: [PATCH 01/11] fixing documentation cross-reference links Signed-off-by: Alessandro Comodi --- README.md | 12 +- UPDATING-THE-DOCS.md | 12 +- docs/architecture/code_of_conduct.md | 1 + docs/architecture/copying.md | 1 + docs/architecture/updating_the_docs.md | 1 + docs/conf.py | 8 +- docs/db_dev_process/contributing.md | 1 + docs/db_dev_process/fuzzers/index | 1 + docs/db_dev_process/fuzzers/index.rst | 101 ++++++++++++++ docs/db_dev_process/minitests/index | 1 + docs/db_dev_process/minitests/index.rst | 29 ++++ docs/db_dev_process/parts.rst | 115 ---------------- docs/index.rst | 6 + docs/markdown_code_symlinks.py | 173 ++++++++++++++++-------- 14 files changed, 273 insertions(+), 189 deletions(-) create mode 120000 docs/architecture/code_of_conduct.md create mode 120000 docs/architecture/copying.md create mode 120000 docs/architecture/updating_the_docs.md create mode 120000 docs/db_dev_process/contributing.md create mode 120000 docs/db_dev_process/fuzzers/index create mode 100644 docs/db_dev_process/fuzzers/index.rst create mode 120000 docs/db_dev_process/minitests/index create mode 100644 docs/db_dev_process/minitests/index.rst diff --git a/README.md b/README.md index 68d1f6b0..c0f2f02c 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](experiments) +### [Experiments](https://github.com/SymbiFlow/prjxray/blob/master/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](tools) & [Libs](libs) +### [Tools](https://github.com/SymbiFlow/prjxray/blob/master/tools) & [Libs](https://github.com/SymbiFlow/prjxray/blob/master/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](utils) directory and could be actively used in other +those in the [utils](https://github.com/SymbiFlow/prjxray/blob/master/utils) directory and could be actively used in other projects. -### [Utils](utils) +### [Utils](https://github.com/SymbiFlow/prjxray/blob/master/utils) Utils are various tools which are still highly experimental. These tools should only be used inside this repository. -### [Third Party](third_party) +### [Third Party](https://github.com/SymbiFlow/prjxray/blob/master/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](database) directory. +bitstream format in the [database](https://github.com/SymbiFlow/prjxray/blob/master/database) directory. As running all these fuzzers can take significant time, [Tim 'mithro' Ansell ](https://github.com/mithro) has graciously diff --git a/UPDATING-THE-DOCS.md b/UPDATING-THE-DOCS.md index 267fa5bd..f8b985b9 100644 --- a/UPDATING-THE-DOCS.md +++ b/UPDATING-THE-DOCS.md @@ -8,7 +8,7 @@ The reason for using the `docs` branch is to avoid running the full CI test suit Updating the docs is a three-step process: Make your updates, test your updates, send a pull request. -# 1. Make your updates +## 1. Make your updates The standard Project X-Ray [contribution guidelines](CONTRIBUTING.md) apply to doc updates too. @@ -16,18 +16,18 @@ doc updates too. Follow your usual process for updating content on GitHub. See GitHub's guide to [working with forks](https://help.github.com/articles/working-with-forks/). -# 2. Test your updates +## 2. Test your updates Before sending a pull request with your doc updates, you need to check the effects of your changes on the page you've updated and on the docs as a whole. -## Check your markup +### Check your markup There are a few places on the web where you can view ReStructured Text rendered as HTML. For example: [https://livesphinx.herokuapp.com/](https://livesphinx.herokuapp.com/) -## Perform basic tests: make html and linkcheck +### Perform basic tests: make html and linkcheck If your changes are quite simple, you can perform a few basic checks before sending a pull request. At minimum: @@ -85,7 +85,7 @@ Steps in detail, on Linux: 1. To leave the shell, type: `exit`. -## Perform more comprehensive testing on your own staging doc site +### Perform more comprehensive testing on your own staging doc site If your changes are more comprehensive, you should do a full test of your fork of the docs before sending a pull request to the Project X-Ray repo. You can @@ -125,7 +125,7 @@ Follow these steps to create your own staging doc site on Read the Docs (RtD): guide](https://docs.readthedocs.io/en/latest/getting_started.html#import-docs) for more info. -# 3. Send a pull request +## 3. Send a pull request Follow your standard GitHub process to send a pull request to the Project X-Ray repo. See the GitHub guide to [creating a pull request from a diff --git a/docs/architecture/code_of_conduct.md b/docs/architecture/code_of_conduct.md new file mode 120000 index 00000000..a3613c99 --- /dev/null +++ b/docs/architecture/code_of_conduct.md @@ -0,0 +1 @@ +../../CODE_OF_CONDUCT.md \ No newline at end of file diff --git a/docs/architecture/copying.md b/docs/architecture/copying.md new file mode 120000 index 00000000..7d29222e --- /dev/null +++ b/docs/architecture/copying.md @@ -0,0 +1 @@ +../../COPYING \ No newline at end of file diff --git a/docs/architecture/updating_the_docs.md b/docs/architecture/updating_the_docs.md new file mode 120000 index 00000000..32e89853 --- /dev/null +++ b/docs/architecture/updating_the_docs.md @@ -0,0 +1 @@ +../../UPDATING-THE-DOCS.md \ No newline at end of file diff --git a/docs/conf.py b/docs/conf.py index 03e354be..aa8994b0 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 MarkdownCodeSymlinks +from markdown_code_symlinks import LinkParser, PrjxrayDomain # -- General configuration ------------------------------------------------ @@ -52,7 +52,7 @@ templates_path = ['_templates'] # You can specify multiple suffix as a list of string: source_suffix = ['.rst', '.md'] source_parsers = { - '.md': 'recommonmark.parser.CommonMarkParser', + '.md': 'markdown_code_symlinks.LinkParser', } # The master toctree document. @@ -196,9 +196,9 @@ intersphinx_mapping = {'https://docs.python.org/': None} def setup(app): - MarkdownCodeSymlinks.find_links() + PrjxrayDomain.find_links() + app.add_domain(PrjxrayDomain) app.add_config_value( 'recommonmark_config', { 'github_code_repo': 'https://github.com/SymbiFlow/prjxray', }, True) - app.add_transform(MarkdownCodeSymlinks) diff --git a/docs/db_dev_process/contributing.md b/docs/db_dev_process/contributing.md new file mode 120000 index 00000000..f939e75f --- /dev/null +++ b/docs/db_dev_process/contributing.md @@ -0,0 +1 @@ +../../CONTRIBUTING.md \ No newline at end of file diff --git a/docs/db_dev_process/fuzzers/index b/docs/db_dev_process/fuzzers/index new file mode 120000 index 00000000..8e8d4720 --- /dev/null +++ b/docs/db_dev_process/fuzzers/index @@ -0,0 +1 @@ +../../../fuzzers \ No newline at end of file diff --git a/docs/db_dev_process/fuzzers/index.rst b/docs/db_dev_process/fuzzers/index.rst new file mode 100644 index 00000000..d45fb1d1 --- /dev/null +++ b/docs/db_dev_process/fuzzers/index.rst @@ -0,0 +1,101 @@ +Fuzzers +======= +Fuzzers are things that generate a design, feed it to Vivado, and look at the resulting bitstream to make some conclusion. +This is how the contents of the database are generated. + +The general idea behind fuzzers is to pick some element in the device (say a block RAM or IOB) to target. +If you picked the IOB (no one is working on that yet), you'd write a design that is implemented in a specific IOB. +Then you'd create a program that creates variations of the design (called specimens) that vary the design parameters, for example, changing the configuration of a single pin. + +A lot of this program is TCL that runs inside Vivado to change the design parameters, because it is a bit faster to load in one Verilog model and use TCL to replicate it with varying inputs instead of having different models and loading them individually. + +By looking at all the resulting specimens, you can correlate which bits in which frame correspond to a particular choice in the design. + +Looking at the implemented design in Vivado with "Show Routing Resources" turned on is quite helpful in understanding what all choices exist. + +Configurable Logic Blocks (CLB) +------------------------------- + +.. toctree:: + :maxdepth: 1 + :glob: + + *clb* + +Block RAM (BRAM) +---------------- + +.. toctree:: + :maxdepth: 1 + :glob: + + *bram* + +Input / Output (IOB) +-------------------- + +.. toctree:: + :maxdepth: 1 + :glob: + + *iob* + +Clocking (CMT, PLL, BUFG, etc) +------------------------------ + +.. toctree:: + :maxdepth: 1 + :glob: + + *clk* + *cmt* + +Programmable Interconnect Points (PIPs) +--------------------------------------- + +.. toctree:: + :maxdepth: 1 + :glob: + + *int* + *pip* + +Hard Block Fuzzers +------------------ + +.. toctree:: + :maxdepth: 1 + :glob: + + *xadc + +Grid and Wire +------------- + +.. toctree:: + :maxdepth: 1 + :glob: + + tilegrid + tileconn + ordered_wires + get_counts + dump_all + +Timing +------ + +.. toctree:: + :maxdepth: 1 + :glob: + + timing + +All Fuzzers +----------- + +.. toctree:: + :maxdepth: 1 + :glob: + + * diff --git a/docs/db_dev_process/minitests/index b/docs/db_dev_process/minitests/index new file mode 120000 index 00000000..9f989966 --- /dev/null +++ b/docs/db_dev_process/minitests/index @@ -0,0 +1 @@ +../../../minitests \ No newline at end of file diff --git a/docs/db_dev_process/minitests/index.rst b/docs/db_dev_process/minitests/index.rst new file mode 100644 index 00000000..2e06adb6 --- /dev/null +++ b/docs/db_dev_process/minitests/index.rst @@ -0,0 +1,29 @@ +Minitests +========= + +Minitests are experiments to figure out how things work. They allow us to understand how to better write new fuzzers. + +.. toctree:: + :maxdepth: 1 + :glob: + + clb-bused + clb-carry_cin_cyinit + clb-configs + clb-muxf8 + clkbuf + eccbits + fixedpnr + index.rst + litex + lvb_long_mux + nodes_wires_list + partial_reconfig_flow + picorv32-v + picorv32-y + pip-switchboxes + roi_harness + srl + tiles_wires_pips + timing + util diff --git a/docs/db_dev_process/parts.rst b/docs/db_dev_process/parts.rst index 63ac0929..be6dc0d2 100644 --- a/docs/db_dev_process/parts.rst +++ b/docs/db_dev_process/parts.rst @@ -1,118 +1,3 @@ - -Fuzzers -======= -Fuzzers are things that generate a design, feed it to Vivado, and look at the resulting bitstream to make some conclusion. -This is how the contents of the database are generated. - -The general idea behind fuzzers is to pick some element in the device (say a block RAM or IOB) to target. -If you picked the IOB (no one is working on that yet), you'd write a design that is implemented in a specific IOB. -Then you'd create a program that creates variations of the design (called specimens) that vary the design parameters, for example, changing the configuration of a single pin. - -A lot of this program is TCL that runs inside Vivado to change the design parameters, because it is a bit faster to load in one Verilog model and use TCL to replicate it with varying inputs instead of having different models and loading them individually. - -By looking at all the resulting specimens, you can correlate which bits in which frame correspond to a particular choice in the design. - -Looking at the implemented design in Vivado with "Show Routing Resources" turned on is quite helpful in understanding what all choices exist. - -Configurable Logic Blocks (CLB) -------------------------------- - -.. toctree:: - :maxdepth: 1 - :glob: - - fuzzers/*clb* - -Block RAM (BRAM) ----------------- - -.. toctree:: - :maxdepth: 1 - :glob: - - fuzzers/*bram* - -Input / Output (IOB) --------------------- - -.. toctree:: - :maxdepth: 1 - :glob: - - fuzzers/*iob* - -Clocking (CMT, PLL, BUFG, etc) ------------------------------- - -.. toctree:: - :maxdepth: 1 - :glob: - - fuzzers/*clk* - fuzzers/*cmt* - -Programmable Interconnect Points (PIPs) ---------------------------------------- - -.. toctree:: - :maxdepth: 1 - :glob: - - fuzzers/*int* - fuzzers/*pip* - -Hard Block Fuzzers ------------------- - -.. toctree:: - :maxdepth: 1 - :glob: - - fuzzers/*xadc - -Grid and Wire -------------- - -.. toctree:: - :maxdepth: 1 - :glob: - - fuzzers/tilegrid - fuzzers/tileconn - fuzzers/ordered_wires - fuzzers/get_counts - fuzzers/dump_all - -Timing ------- - -.. toctree:: - :maxdepth: 1 - :glob: - - fuzzers/timing - -All Fuzzers ------------ - -.. toctree:: - :maxdepth: 1 - :glob: - - fuzzers/* - -Minitests -========= - -Minitests are experiments to figure out how things work. They allow us to understand how to better write new fuzzers. - -.. toctree:: - :maxdepth: 1 - :caption: Current Minitests - :glob: - - minitests/* - Tools ===== diff --git a/docs/index.rst b/docs/index.rst index 7dfe6b38..25ef7215 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -24,12 +24,18 @@ to develop a free and open Verilog to bitstream toolchain for these devices. architecture/dram_configuration architecture/glossary architecture/reference + architecture/code_of_conduct + architecture/updating_the_docs + architecture/copying .. toctree:: :maxdepth: 2 :caption: Database Development Process db_dev_process/readme + db_dev_process/contributing + db_dev_process/fuzzers/index + db_dev_process/minitests/index db_dev_process/parts .. toctree:: diff --git a/docs/markdown_code_symlinks.py b/docs/markdown_code_symlinks.py index 1955493e..af080449 100644 --- a/docs/markdown_code_symlinks.py +++ b/docs/markdown_code_symlinks.py @@ -1,7 +1,19 @@ import logging -import os +import os, sys +from os.path import splitext +from docutils import nodes +from sphinx import addnodes +from sphinx.roles import XRefRole +from sphinx.domains import Domain +from sphinx.util.nodes import make_refnode + +if sys.version_info < (3, 0): + from urlparse import urlparse, unquote +else: + from urllib.parse import urlparse, unquote + +from recommonmark import parser -from recommonmark import transform """ Allow linking of Markdown documentation from the source code tree into the Sphinx documentation tree. @@ -13,7 +25,6 @@ We also want links from two Markdown documents found in the Sphinx docs to work, so that is also fixed up. """ - def path_contains(parent_path, child_path): """Check a path contains another path. @@ -55,9 +66,21 @@ def relative(parent_dir, child_path): return os.path.relpath(child_path, start=parent_dir) -class MarkdownCodeSymlinks(transform.AutoStructify, object): +class PrjxrayDomain(Domain): + """ + Extension of the Domain class to implement custom cross-reference links + solve methodology + """ + + name = 'prjxray' + label = 'Prjxray' + + roles = { + 'xref': XRefRole(), + } + docs_root_dir = os.path.realpath(os.path.dirname(__file__)) - code_root_dir = os.path.realpath(os.path.join(docs_root_dir, "..", "..")) + code_root_dir = os.path.realpath(os.path.join(docs_root_dir, "..")) mapping = { 'docs2code': {}, @@ -81,6 +104,7 @@ Assertion error! Document already in mapping! New Value: {} Current Value: {} """.format(docs_rel, cls.mapping['docs2code'][docs_rel]) + assert code_rel not in cls.mapping['code2docs'], """\ Assertion error! Document already in mapping! New Value: {} @@ -94,6 +118,26 @@ Current Value: {} def find_links(cls): """Walk the docs dir and find links to docs in the code dir.""" for root, dirs, files in os.walk(cls.docs_root_dir): + for dname in dirs: + dpath = os.path.abspath(os.path.join(root, dname)) + + if not os.path.islink(dpath): + continue + + link_path = os.path.join(root, os.readlink(dpath)) + # Is link outside the code directory? + if not path_contains(cls.code_root_dir, link_path): + continue + + # Is link internal to the docs directory? + if path_contains(cls.docs_root_dir, link_path): + continue + + docs_rel = cls.relative_docs(dpath) + code_rel = cls.relative_code(link_path) + + cls.add_mapping(docs_rel, code_rel) + for fname in files: fpath = os.path.abspath(os.path.join(root, fname)) @@ -113,66 +157,79 @@ Current Value: {} code_rel = cls.relative_code(link_path) cls.add_mapping(docs_rel, code_rel) + import pprint pprint.pprint(cls.mapping) - @property - def url_resolver(self): - return self._url_resolver + @classmethod + def remove_extension(cls, path): + return filename - @url_resolver.setter - def url_resolver(self, value): - print(self, value) - - # Resolve a link from one markdown to another document. - def _url_resolver(self, ourl): - """Resolve a URL found in a markdown file.""" - assert self.docs_root_dir == os.path.realpath(self.root_dir), """\ -Configuration error! Document Root != Current Root -Document Root: {} - Current Root: {} -""".format(self.docs_root_dir, self.root_dir) - - src_path = os.path.abspath(self.document['source']) - src_dir = os.path.dirname(src_path) - dst_path = os.path.abspath(os.path.join(self.docs_root_dir, ourl)) - dst_rsrc = os.path.relpath(dst_path, start=src_dir) - - src_rdoc = self.relative_docs(src_path) - - print - print("url_resolver") - print(src_path) - print(dst_path) - print(dst_rsrc) - print(src_rdoc) - - # Is the source document a linked one? - if src_rdoc not in self.mapping['docs2code']: - # Don't do any rewriting on non-linked markdown. - url = ourl - - # Is the destination also inside docs? - elif dst_rsrc not in self.mapping['code2docs']: - # Return a path to the GitHub repo. - url = "{}/blob/master/{}".format( - self.config['github_code_repo'], dst_rsrc) + # Overriden method to solve the cross-reference link + def resolve_xref(self, env, fromdocname, builder, + typ, target, node, contnode): + if '#' in target: + todocname, targetid = target.split('#') else: - url = os.path.relpath( - os.path.join( - self.docs_root_dir, self.mapping['code2docs'][dst_rsrc]), - start=src_dir) - base_url, ext = os.path.splitext(url) - assert ext in (".md", - ".markdown"), ("Unknown extension {}".format(ext)) - url = "{}.html".format(base_url) + todocname = target + targetid = '' - print("---") - print(ourl) - print(url) - print - return url + # 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]) + + print(newnode) + return newnode + + def resolve_any_xref(self, env, fromdocname, builder, + target, node, contnode): + res = self.resolve_xref(env, fromdocname, builder, 'xref', target, node, contnode) + return [('prjxray:xref', res)] + +class LinkParser(parser.CommonMarkParser, object): + def visit_link(self, mdnode): + ref_node = nodes.reference() + + destination = mdnode.destination + + ref_node.line = self._get_line(mdnode) + if mdnode.title: + ref_node['title'] = mdnode.title + + url_check = urlparse(destination) + # If there's not a url scheme (e.g. 'https' for 'https:...' links), + # or there is a scheme but it's not in the list of known_url_schemes, + # then assume it's a cross-reference and pass it to Sphinx as an `:any:` ref. + known_url_schemes = self.config.get('known_url_schemes') + if known_url_schemes: + scheme_known = url_check.scheme in known_url_schemes + else: + scheme_known = bool(url_check.scheme) + + is_dest_xref = url_check.fragment and destination[:1] != '#' + + ref_node['refuri'] = destination + next_node = ref_node + + # Adds pending-xref wrapper to unsolvable cross-references + if (is_dest_xref or not url_check.fragment) and not scheme_known: + wrap_node = addnodes.pending_xref( + reftarget=unquote(destination), + reftype='xref', + refdomain='prjxray', # Added to enable cross-linking + refexplicit=True, + refwarn=True + ) + # TODO also not correct sourcepos + wrap_node.line = self._get_line(mdnode) + if mdnode.title: + wrap_node['title'] = mdnode.title + wrap_node.append(ref_node) + next_node = wrap_node + + self.current_node.append(next_node) + self.current_node = ref_node if __name__ == "__main__": import doctest From 887c5b67a9a1881dc40e29daf46d7f927f21148c Mon Sep 17 00:00:00 2001 From: Alessandro Comodi Date: Mon, 2 Sep 2019 17:45:45 +0200 Subject: [PATCH 02/11] exclude docs in `make test` Signed-off-by: Alessandro Comodi --- Makefile | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Makefile b/Makefile index 73a04051..e314689c 100644 --- a/Makefile +++ b/Makefile @@ -34,7 +34,7 @@ build: # Run tests of code. # ------------------------ -TEST_EXCLUDE = $(foreach x,$(ALL_EXCLUDE) fuzzers minitests experiments,--ignore $(x)) +TEST_EXCLUDE = $(foreach x,$(ALL_EXCLUDE) docs fuzzers minitests experiments,--ignore $(x)) test: test-py test-cpp @true From 78fd7843a5c1d6239bbefb997a526822ec1ee0b7 Mon Sep 17 00:00:00 2001 From: Alessandro Comodi Date: Mon, 2 Sep 2019 17:46:16 +0200 Subject: [PATCH 03/11] run make format Signed-off-by: Alessandro Comodi --- docs/markdown_code_symlinks.py | 21 ++++++++++++--------- 1 file changed, 12 insertions(+), 9 deletions(-) diff --git a/docs/markdown_code_symlinks.py b/docs/markdown_code_symlinks.py index af080449..a3630cac 100644 --- a/docs/markdown_code_symlinks.py +++ b/docs/markdown_code_symlinks.py @@ -13,7 +13,6 @@ else: from urllib.parse import urlparse, unquote from recommonmark import parser - """ Allow linking of Markdown documentation from the source code tree into the Sphinx documentation tree. @@ -25,6 +24,7 @@ We also want links from two Markdown documents found in the Sphinx docs to work, so that is also fixed up. """ + def path_contains(parent_path, child_path): """Check a path contains another path. @@ -166,8 +166,8 @@ Current Value: {} return filename # Overriden method to solve the cross-reference link - def resolve_xref(self, env, fromdocname, builder, - typ, target, node, contnode): + def resolve_xref( + self, env, fromdocname, builder, typ, target, node, contnode): if '#' in target: todocname, targetid = target.split('#') else: @@ -177,16 +177,19 @@ Current Value: {} # 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]) + newnode = make_refnode( + builder, fromdocname, todocname, targetid, contnode[0]) print(newnode) return newnode - def resolve_any_xref(self, env, fromdocname, builder, - target, node, contnode): - res = self.resolve_xref(env, fromdocname, builder, 'xref', target, node, contnode) + def resolve_any_xref( + self, env, fromdocname, builder, target, node, contnode): + res = self.resolve_xref( + env, fromdocname, builder, 'xref', target, node, contnode) return [('prjxray:xref', res)] + class LinkParser(parser.CommonMarkParser, object): def visit_link(self, mdnode): ref_node = nodes.reference() @@ -219,8 +222,7 @@ class LinkParser(parser.CommonMarkParser, object): reftype='xref', refdomain='prjxray', # Added to enable cross-linking refexplicit=True, - refwarn=True - ) + refwarn=True) # TODO also not correct sourcepos wrap_node.line = self._get_line(mdnode) if mdnode.title: @@ -231,6 +233,7 @@ class LinkParser(parser.CommonMarkParser, object): self.current_node.append(next_node) self.current_node = ref_node + if __name__ == "__main__": import doctest doctest.testmod() From 78ffa253ff1810f10699ccf3bb56d7a7d2105533 Mon Sep 17 00:00:00 2001 From: Alessandro Comodi Date: Tue, 3 Sep 2019 11:17:56 +0200 Subject: [PATCH 04/11] removing unnecessary print Signed-off-by: Alessandro Comodi --- docs/markdown_code_symlinks.py | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/markdown_code_symlinks.py b/docs/markdown_code_symlinks.py index a3630cac..5b746bda 100644 --- a/docs/markdown_code_symlinks.py +++ b/docs/markdown_code_symlinks.py @@ -180,7 +180,6 @@ Current Value: {} newnode = make_refnode( builder, fromdocname, todocname, targetid, contnode[0]) - print(newnode) return newnode def resolve_any_xref( From 68eb42652715723ab40c6f5b681eea9cca7c03b9 Mon Sep 17 00:00:00 2001 From: Alessandro Comodi Date: Wed, 4 Sep 2019 13:01:23 +0200 Subject: [PATCH 05/11] 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 From aa0fa7ba759d580fe170a4cd10b6bb4891ecf4b6 Mon Sep 17 00:00:00 2001 From: Alessandro Comodi Date: Wed, 4 Sep 2019 15:39:51 +0200 Subject: [PATCH 06/11] using markdown as package from repository also moved all documenation sources in `src` directory Signed-off-by: Alessandro Comodi --- docs/.gitignore | 4 +- docs/Makefile | 18 +- docs/architecture/code_of_conduct.md | 1 - docs/architecture/copying.md | 1 - docs/architecture/updating_the_docs.md | 1 - docs/db_dev_process/contributing.md | 1 - docs/db_dev_process/fuzzers/index | 1 - docs/db_dev_process/minitests/fixedpnr.md | 1 - docs/db_dev_process/minitests/index | 1 - .../minitests/partial_reconfig_flow.md | 1 - docs/db_dev_process/minitests/picorv32-v.md | 1 - docs/db_dev_process/minitests/picorv32-y.md | 1 - docs/db_dev_process/minitests/roi_harness.md | 1 - docs/db_dev_process/readme.md | 1 - docs/markdown_code_symlinks.py | 250 ------------------ docs/requirements.txt | 3 + .../architecture/bitstream_format.rst | 0 docs/src/architecture/code_of_conduct.md | 1 + docs/{ => src}/architecture/configuration.rst | 0 docs/src/architecture/copying.md | 1 + .../architecture/dram_configuration.rst | 0 docs/{ => src}/architecture/glossary.rst | 0 docs/{ => src}/architecture/interconnect.rst | 0 docs/{ => src}/architecture/overview.rst | 0 docs/{ => src}/architecture/reference.rst | 0 docs/src/architecture/updating_the_docs.md | 1 + docs/{ => src}/conf.py | 7 +- docs/src/db_dev_process/contributing.md | 1 + docs/src/db_dev_process/fuzzers/index | 1 + .../db_dev_process/fuzzers/index.rst | 0 docs/src/db_dev_process/minitests/index | 1 + .../db_dev_process/minitests/index.rst | 0 docs/{ => src}/db_dev_process/parts.rst | 0 docs/src/db_dev_process/readme.md | 1 + docs/{ => src}/format/db.rst | 0 docs/{ => src}/format/tile.rst | 0 docs/{ => src}/index.rst | 0 37 files changed, 27 insertions(+), 274 deletions(-) delete mode 120000 docs/architecture/code_of_conduct.md delete mode 120000 docs/architecture/copying.md delete mode 120000 docs/architecture/updating_the_docs.md delete mode 120000 docs/db_dev_process/contributing.md delete mode 120000 docs/db_dev_process/fuzzers/index delete mode 120000 docs/db_dev_process/minitests/fixedpnr.md delete mode 120000 docs/db_dev_process/minitests/index delete mode 120000 docs/db_dev_process/minitests/partial_reconfig_flow.md delete mode 120000 docs/db_dev_process/minitests/picorv32-v.md delete mode 120000 docs/db_dev_process/minitests/picorv32-y.md delete mode 120000 docs/db_dev_process/minitests/roi_harness.md delete mode 120000 docs/db_dev_process/readme.md delete mode 100644 docs/markdown_code_symlinks.py rename docs/{ => src}/architecture/bitstream_format.rst (100%) create mode 120000 docs/src/architecture/code_of_conduct.md rename docs/{ => src}/architecture/configuration.rst (100%) create mode 120000 docs/src/architecture/copying.md rename docs/{ => src}/architecture/dram_configuration.rst (100%) rename docs/{ => src}/architecture/glossary.rst (100%) rename docs/{ => src}/architecture/interconnect.rst (100%) rename docs/{ => src}/architecture/overview.rst (100%) rename docs/{ => src}/architecture/reference.rst (100%) create mode 120000 docs/src/architecture/updating_the_docs.md rename docs/{ => src}/conf.py (95%) create mode 120000 docs/src/db_dev_process/contributing.md create mode 120000 docs/src/db_dev_process/fuzzers/index rename docs/{ => src}/db_dev_process/fuzzers/index.rst (100%) create mode 120000 docs/src/db_dev_process/minitests/index rename docs/{ => src}/db_dev_process/minitests/index.rst (100%) rename docs/{ => src}/db_dev_process/parts.rst (100%) create mode 120000 docs/src/db_dev_process/readme.md rename docs/{ => src}/format/db.rst (100%) rename docs/{ => src}/format/tile.rst (100%) rename docs/{ => src}/index.rst (100%) diff --git a/docs/.gitignore b/docs/.gitignore index 9d7ce536..c8d939ef 100644 --- a/docs/.gitignore +++ b/docs/.gitignore @@ -1,3 +1,3 @@ _build -db_dev_process/fuzzers/*.md -db_dev_process/minitests/*.md +src/db_dev_process/fuzzers/*.md +src/db_dev_process/minitests/*.md diff --git a/docs/Makefile b/docs/Makefile index d845e77b..02bebc6c 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -8,7 +8,7 @@ SPHINXOPTS = SPHINXBUILD = sphinx-build SPHINXAUTOBUILD = sphinx-autobuild SPHINXPROJ = ProjectX-Ray -SOURCEDIR = . +SOURCEDIR = src BUILDDIR = _build # Put it first so that "make" without argument is like "make help". @@ -22,10 +22,10 @@ livehtml: # Update fuzzer / minitest markdown links. fuzzers-links: - @mkdir -p $(MAKEDIR)/db_dev_process/fuzzers - @cd $(MAKEDIR)/db_dev_process/fuzzers && rm -f *.md - @cd $(MAKEDIR)/db_dev_process/fuzzers && \ - for i in ../../../fuzzers/*; do \ + @mkdir -p $(MAKEDIR)/${SOURCEDIR}/db_dev_process/fuzzers + @cd $(MAKEDIR)/${SOURCEDIR}/db_dev_process/fuzzers && rm -f *.md + @cd $(MAKEDIR)/${SOURCEDIR}/db_dev_process/fuzzers && \ + for i in ../../../../fuzzers/*; do \ n=$$(basename $$i | sed -e's/^[0-9][0-9][0-9]-//'); \ if [ ! -d $$i ]; then \ continue; \ @@ -42,10 +42,10 @@ fuzzers-links: done minitests-links: - @mkdir -p $(MAKEDIR)/db_dev_process/minitests - @cd $(MAKEDIR)/db_dev_process/minitests && rm -f *.md - @cd $(MAKEDIR)/db_dev_process/minitests && \ - for i in ../../../minitests/*; do \ + @mkdir -p $(MAKEDIR)/${SOURCEDIR}/db_dev_process/minitests + @cd $(MAKEDIR)/${SOURCEDIR}/db_dev_process/minitests && rm -f *.md + @cd $(MAKEDIR)/${SOURCEDIR}/db_dev_process/minitests && \ + for i in ../../../../minitests/*; do \ n=$$(basename $$i | sed -e's/^[0-9][0-9][0-9]-//'); \ if [ ! -d $$i ]; then \ continue; \ diff --git a/docs/architecture/code_of_conduct.md b/docs/architecture/code_of_conduct.md deleted file mode 120000 index a3613c99..00000000 --- a/docs/architecture/code_of_conduct.md +++ /dev/null @@ -1 +0,0 @@ -../../CODE_OF_CONDUCT.md \ No newline at end of file diff --git a/docs/architecture/copying.md b/docs/architecture/copying.md deleted file mode 120000 index 7d29222e..00000000 --- a/docs/architecture/copying.md +++ /dev/null @@ -1 +0,0 @@ -../../COPYING \ No newline at end of file diff --git a/docs/architecture/updating_the_docs.md b/docs/architecture/updating_the_docs.md deleted file mode 120000 index 32e89853..00000000 --- a/docs/architecture/updating_the_docs.md +++ /dev/null @@ -1 +0,0 @@ -../../UPDATING-THE-DOCS.md \ No newline at end of file diff --git a/docs/db_dev_process/contributing.md b/docs/db_dev_process/contributing.md deleted file mode 120000 index f939e75f..00000000 --- a/docs/db_dev_process/contributing.md +++ /dev/null @@ -1 +0,0 @@ -../../CONTRIBUTING.md \ No newline at end of file diff --git a/docs/db_dev_process/fuzzers/index b/docs/db_dev_process/fuzzers/index deleted file mode 120000 index 8e8d4720..00000000 --- a/docs/db_dev_process/fuzzers/index +++ /dev/null @@ -1 +0,0 @@ -../../../fuzzers \ No newline at end of file diff --git a/docs/db_dev_process/minitests/fixedpnr.md b/docs/db_dev_process/minitests/fixedpnr.md deleted file mode 120000 index 406424c0..00000000 --- a/docs/db_dev_process/minitests/fixedpnr.md +++ /dev/null @@ -1 +0,0 @@ -../../../minitests/fixedpnr/README.md \ No newline at end of file diff --git a/docs/db_dev_process/minitests/index b/docs/db_dev_process/minitests/index deleted file mode 120000 index 9f989966..00000000 --- a/docs/db_dev_process/minitests/index +++ /dev/null @@ -1 +0,0 @@ -../../../minitests \ No newline at end of file diff --git a/docs/db_dev_process/minitests/partial_reconfig_flow.md b/docs/db_dev_process/minitests/partial_reconfig_flow.md deleted file mode 120000 index 1a9a42e7..00000000 --- a/docs/db_dev_process/minitests/partial_reconfig_flow.md +++ /dev/null @@ -1 +0,0 @@ -../../../minitests/partial_reconfig_flow/README.md \ No newline at end of file diff --git a/docs/db_dev_process/minitests/picorv32-v.md b/docs/db_dev_process/minitests/picorv32-v.md deleted file mode 120000 index d0d80c60..00000000 --- a/docs/db_dev_process/minitests/picorv32-v.md +++ /dev/null @@ -1 +0,0 @@ -../../../minitests/picorv32-v/README.md \ No newline at end of file diff --git a/docs/db_dev_process/minitests/picorv32-y.md b/docs/db_dev_process/minitests/picorv32-y.md deleted file mode 120000 index 38591c50..00000000 --- a/docs/db_dev_process/minitests/picorv32-y.md +++ /dev/null @@ -1 +0,0 @@ -../../../minitests/picorv32-y/README.md \ No newline at end of file diff --git a/docs/db_dev_process/minitests/roi_harness.md b/docs/db_dev_process/minitests/roi_harness.md deleted file mode 120000 index 5a587711..00000000 --- a/docs/db_dev_process/minitests/roi_harness.md +++ /dev/null @@ -1 +0,0 @@ -../../../minitests/roi_harness/README.md \ No newline at end of file diff --git a/docs/db_dev_process/readme.md b/docs/db_dev_process/readme.md deleted file mode 120000 index fe840054..00000000 --- a/docs/db_dev_process/readme.md +++ /dev/null @@ -1 +0,0 @@ -../../README.md \ No newline at end of file diff --git a/docs/markdown_code_symlinks.py b/docs/markdown_code_symlinks.py deleted file mode 100644 index f43bfcaa..00000000 --- a/docs/markdown_code_symlinks.py +++ /dev/null @@ -1,250 +0,0 @@ -import logging -import os, sys -from os.path import splitext -from docutils import nodes -from sphinx import addnodes -from sphinx.roles import XRefRole -from sphinx.domains import Domain -from sphinx.util.nodes import make_refnode - -if sys.version_info < (3, 0): - from urlparse import urlparse, unquote -else: - from urllib.parse import urlparse, unquote - -from recommonmark import parser -""" -Allow linking of Markdown documentation from the source code tree into the Sphinx -documentation tree. - -The Markdown documents will have links relative to the source code root, rather -than the place they are now linked too - this code fixes these paths up. - -We also want links from two Markdown documents found in the Sphinx docs to -work, so that is also fixed up. -""" - - -def path_contains(parent_path, child_path): - """Check a path contains another path. - - >>> path_contains("a/b", "a/b") - True - >>> path_contains("a/b", "a/b/") - True - >>> path_contains("a/b", "a/b/c") - True - >>> path_contains("a/b", "c") - False - >>> path_contains("a/b", "c/b") - False - >>> path_contains("a/b", "c/../a/b/d") - True - >>> path_contains("../a/b", "../a/b/d") - True - >>> path_contains("../a/b", "../a/c") - False - >>> path_contains("a", "abc") - False - >>> path_contains("aa", "abc") - False - """ - # Append a separator to the end of both paths to work around the fact that - # os.path.commonprefix does character by character comparisons rather than - # path segment by path segment. - parent_path = os.path.join(os.path.normpath(parent_path), '') - child_path = os.path.join(os.path.normpath(child_path), '') - common_path = os.path.commonprefix((parent_path, child_path)) - return common_path == parent_path - - -def relative(parent_dir, child_path): - """Get the relative between a path that contains another path.""" - child_dir = os.path.dirname(child_path) - assert path_contains(parent_dir, child_dir), "{} not inside {}".format( - child_path, parent_dir) - return os.path.relpath(child_path, start=parent_dir) - - -class MarkdownSymlinksDomain(Domain): - """ - Extension of the Domain class to implement custom cross-reference links - solve methodology - """ - - name = 'markdown_symlinks' - label = 'MarkdownSymlinks' - - roles = { - 'xref': XRefRole(), - } - - docs_root_dir = os.path.realpath(os.path.dirname(__file__)) - code_root_dir = os.path.realpath(os.path.join(docs_root_dir, "..")) - - mapping = { - 'docs2code': {}, - 'code2docs': {}, - } - - github_repo_url = "" - github_repo_branch = "" - - @classmethod - def relative_code(cls, url): - """Get a value relative to the code directory.""" - return relative(cls.code_root_dir, url) - - @classmethod - def relative_docs(cls, url): - """Get a value relative to the docs directory.""" - return relative(cls.docs_root_dir, url) - - @classmethod - def add_mapping(cls, docs_rel, code_rel): - assert docs_rel not in cls.mapping['docs2code'], """\ -Assertion error! Document already in mapping! - New Value: {} -Current Value: {} -""".format(docs_rel, cls.mapping['docs2code'][docs_rel]) - - assert code_rel not in cls.mapping['code2docs'], """\ -Assertion error! Document already in mapping! - New Value: {} -Current Value: {} -""".format(docs_rel, cls.mapping['code2docs'][code_rel]) - - cls.mapping['docs2code'][docs_rel] = code_rel - cls.mapping['code2docs'][code_rel] = docs_rel - - @classmethod - def find_links(cls): - """Walk the docs dir and find links to docs in the code dir.""" - for root, dirs, files in os.walk(cls.docs_root_dir): - for dname in dirs: - dpath = os.path.abspath(os.path.join(root, dname)) - - if not os.path.islink(dpath): - continue - - link_path = os.path.join(root, os.readlink(dpath)) - # Is link outside the code directory? - if not path_contains(cls.code_root_dir, link_path): - continue - - # Is link internal to the docs directory? - if path_contains(cls.docs_root_dir, link_path): - continue - - docs_rel = cls.relative_docs(dpath) - code_rel = cls.relative_code(link_path) - - cls.add_mapping(docs_rel, code_rel) - - for fname in files: - fpath = os.path.abspath(os.path.join(root, fname)) - - if not os.path.islink(fpath): - continue - - link_path = os.path.join(root, os.readlink(fpath)) - # Is link outside the code directory? - if not path_contains(cls.code_root_dir, link_path): - continue - - # Is link internal to the docs directory? - if path_contains(cls.docs_root_dir, link_path): - continue - - docs_rel = cls.relative_docs(fpath) - code_rel = cls.relative_code(link_path) - - cls.add_mapping(docs_rel, code_rel) - - import pprint - pprint.pprint(cls.mapping) - - @classmethod - 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( - self, env, fromdocname, builder, typ, target, node, contnode): - if '#' in target: - todocname, targetid = target.split('#') - else: - todocname = target - targetid = '' - - 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 = 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 - - def resolve_any_xref( - self, env, fromdocname, builder, target, node, contnode): - res = self.resolve_xref( - env, fromdocname, builder, 'xref', target, node, contnode) - return [('markdown_symlinks:xref', res)] - - -class LinkParser(parser.CommonMarkParser, object): - def visit_link(self, mdnode): - ref_node = nodes.reference() - - destination = mdnode.destination - - ref_node.line = self._get_line(mdnode) - if mdnode.title: - ref_node['title'] = mdnode.title - - url_check = urlparse(destination) - # If there's not a url scheme (e.g. 'https' for 'https:...' links), - # or there is a scheme but it's not in the list of known_url_schemes, - # then assume it's a cross-reference and pass it to Sphinx as an `:any:` ref. - known_url_schemes = self.config.get('known_url_schemes') - if known_url_schemes: - scheme_known = url_check.scheme in known_url_schemes - else: - scheme_known = bool(url_check.scheme) - - is_dest_xref = url_check.fragment and destination[:1] != '#' - - ref_node['refuri'] = destination - next_node = ref_node - - # Adds pending-xref wrapper to unsolvable cross-references - if (is_dest_xref or not url_check.fragment) and not scheme_known: - wrap_node = addnodes.pending_xref( - reftarget=unquote(destination), - reftype='xref', - refdomain='markdown_symlinks', # Added to enable cross-linking - refexplicit=True, - refwarn=True) - # TODO also not correct sourcepos - wrap_node.line = self._get_line(mdnode) - if mdnode.title: - wrap_node['title'] = mdnode.title - wrap_node.append(ref_node) - next_node = wrap_node - - self.current_node.append(next_node) - self.current_node = ref_node - - -if __name__ == "__main__": - import doctest - doctest.testmod() diff --git a/docs/requirements.txt b/docs/requirements.txt index 6edb8579..26dbdc3b 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -7,3 +7,6 @@ recommonmark sphinx-markdown-tables git+https://github.com/SymbiFlow/sphinx_symbiflow_theme sphinxcontrib-napoleon + +# Markdown cross-reference solver library +git+https://github.com/SymbiFlow/markdown-code-symlinks diff --git a/docs/architecture/bitstream_format.rst b/docs/src/architecture/bitstream_format.rst similarity index 100% rename from docs/architecture/bitstream_format.rst rename to docs/src/architecture/bitstream_format.rst diff --git a/docs/src/architecture/code_of_conduct.md b/docs/src/architecture/code_of_conduct.md new file mode 120000 index 00000000..5d525cd1 --- /dev/null +++ b/docs/src/architecture/code_of_conduct.md @@ -0,0 +1 @@ +../../../CODE_OF_CONDUCT.md \ No newline at end of file diff --git a/docs/architecture/configuration.rst b/docs/src/architecture/configuration.rst similarity index 100% rename from docs/architecture/configuration.rst rename to docs/src/architecture/configuration.rst diff --git a/docs/src/architecture/copying.md b/docs/src/architecture/copying.md new file mode 120000 index 00000000..28b80bcc --- /dev/null +++ b/docs/src/architecture/copying.md @@ -0,0 +1 @@ +../../../COPYING \ No newline at end of file diff --git a/docs/architecture/dram_configuration.rst b/docs/src/architecture/dram_configuration.rst similarity index 100% rename from docs/architecture/dram_configuration.rst rename to docs/src/architecture/dram_configuration.rst diff --git a/docs/architecture/glossary.rst b/docs/src/architecture/glossary.rst similarity index 100% rename from docs/architecture/glossary.rst rename to docs/src/architecture/glossary.rst diff --git a/docs/architecture/interconnect.rst b/docs/src/architecture/interconnect.rst similarity index 100% rename from docs/architecture/interconnect.rst rename to docs/src/architecture/interconnect.rst diff --git a/docs/architecture/overview.rst b/docs/src/architecture/overview.rst similarity index 100% rename from docs/architecture/overview.rst rename to docs/src/architecture/overview.rst diff --git a/docs/architecture/reference.rst b/docs/src/architecture/reference.rst similarity index 100% rename from docs/architecture/reference.rst rename to docs/src/architecture/reference.rst diff --git a/docs/src/architecture/updating_the_docs.md b/docs/src/architecture/updating_the_docs.md new file mode 120000 index 00000000..22d86c5d --- /dev/null +++ b/docs/src/architecture/updating_the_docs.md @@ -0,0 +1 @@ +../../../UPDATING-THE-DOCS.md \ No newline at end of file diff --git a/docs/conf.py b/docs/src/conf.py similarity index 95% rename from docs/conf.py rename to docs/src/conf.py index 833cb06b..ac2647ff 100644 --- a/docs/conf.py +++ b/docs/src/conf.py @@ -197,9 +197,14 @@ intersphinx_mapping = {'https://docs.python.org/': None} def setup(app): github_code_repo = 'https://github.com/SymbiFlow/prjxray/' + github_code_branch = 'blob/master/' + docs_root_dir = os.path.realpath(os.path.dirname(__file__)) + code_root_dir = os.path.realpath(os.path.join(docs_root_dir, "..", "..")) + + MarkdownSymlinksDomain.init_domain(github_code_repo, github_code_branch, + docs_root_dir, code_root_dir) MarkdownSymlinksDomain.find_links() - MarkdownSymlinksDomain.add_github_repo(github_code_repo, 'blob/master/') app.add_domain(MarkdownSymlinksDomain) app.add_config_value( 'recommonmark_config', { diff --git a/docs/src/db_dev_process/contributing.md b/docs/src/db_dev_process/contributing.md new file mode 120000 index 00000000..c97564d9 --- /dev/null +++ b/docs/src/db_dev_process/contributing.md @@ -0,0 +1 @@ +../../../CONTRIBUTING.md \ No newline at end of file diff --git a/docs/src/db_dev_process/fuzzers/index b/docs/src/db_dev_process/fuzzers/index new file mode 120000 index 00000000..d78a6674 --- /dev/null +++ b/docs/src/db_dev_process/fuzzers/index @@ -0,0 +1 @@ +../../../../fuzzers/ \ No newline at end of file diff --git a/docs/db_dev_process/fuzzers/index.rst b/docs/src/db_dev_process/fuzzers/index.rst similarity index 100% rename from docs/db_dev_process/fuzzers/index.rst rename to docs/src/db_dev_process/fuzzers/index.rst diff --git a/docs/src/db_dev_process/minitests/index b/docs/src/db_dev_process/minitests/index new file mode 120000 index 00000000..353e56d0 --- /dev/null +++ b/docs/src/db_dev_process/minitests/index @@ -0,0 +1 @@ +../../../../minitests/ \ No newline at end of file diff --git a/docs/db_dev_process/minitests/index.rst b/docs/src/db_dev_process/minitests/index.rst similarity index 100% rename from docs/db_dev_process/minitests/index.rst rename to docs/src/db_dev_process/minitests/index.rst diff --git a/docs/db_dev_process/parts.rst b/docs/src/db_dev_process/parts.rst similarity index 100% rename from docs/db_dev_process/parts.rst rename to docs/src/db_dev_process/parts.rst diff --git a/docs/src/db_dev_process/readme.md b/docs/src/db_dev_process/readme.md new file mode 120000 index 00000000..8a33348c --- /dev/null +++ b/docs/src/db_dev_process/readme.md @@ -0,0 +1 @@ +../../../README.md \ No newline at end of file diff --git a/docs/format/db.rst b/docs/src/format/db.rst similarity index 100% rename from docs/format/db.rst rename to docs/src/format/db.rst diff --git a/docs/format/tile.rst b/docs/src/format/tile.rst similarity index 100% rename from docs/format/tile.rst rename to docs/src/format/tile.rst diff --git a/docs/index.rst b/docs/src/index.rst similarity index 100% rename from docs/index.rst rename to docs/src/index.rst From 399721258ded97ba068551e1dcba998f16c6568d Mon Sep 17 00:00:00 2001 From: Alessandro Comodi Date: Wed, 4 Sep 2019 16:12:15 +0200 Subject: [PATCH 07/11] run make format Signed-off-by: Alessandro Comodi --- docs/src/conf.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/src/conf.py b/docs/src/conf.py index ac2647ff..7137c4a2 100644 --- a/docs/src/conf.py +++ b/docs/src/conf.py @@ -202,8 +202,8 @@ def setup(app): docs_root_dir = os.path.realpath(os.path.dirname(__file__)) code_root_dir = os.path.realpath(os.path.join(docs_root_dir, "..", "..")) - MarkdownSymlinksDomain.init_domain(github_code_repo, github_code_branch, - docs_root_dir, code_root_dir) + MarkdownSymlinksDomain.init_domain( + github_code_repo, github_code_branch, docs_root_dir, code_root_dir) MarkdownSymlinksDomain.find_links() app.add_domain(MarkdownSymlinksDomain) app.add_config_value( From bd92376224a9aabf13696f0f0c65e4e339c34f42 Mon Sep 17 00:00:00 2001 From: Alessandro Comodi Date: Wed, 4 Sep 2019 16:28:28 +0200 Subject: [PATCH 08/11] updated requirements Signed-off-by: Alessandro Comodi --- docs/requirements.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/requirements.txt b/docs/requirements.txt index 26dbdc3b..4f314470 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -9,4 +9,4 @@ git+https://github.com/SymbiFlow/sphinx_symbiflow_theme sphinxcontrib-napoleon # Markdown cross-reference solver library -git+https://github.com/SymbiFlow/markdown-code-symlinks +git+https://github.com/SymbiFlow/sphinxcontrib-markdown-symlinks From 5254a5f82bf894d221403ac7769e77681f506952 Mon Sep 17 00:00:00 2001 From: Alessandro Comodi Date: Mon, 23 Sep 2019 18:20:43 +0200 Subject: [PATCH 09/11] docs: move conf.py in upper directory Signed-off-by: Alessandro Comodi --- docs/{src => }/conf.py | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename docs/{src => }/conf.py (100%) diff --git a/docs/src/conf.py b/docs/conf.py similarity index 100% rename from docs/src/conf.py rename to docs/conf.py From f1fd0c975afc8df6adb3bb90e159604eaf4d40c5 Mon Sep 17 00:00:00 2001 From: Alessandro Comodi Date: Tue, 24 Sep 2019 11:49:00 +0200 Subject: [PATCH 10/11] docs: removed src directory to have working readthedocs build Signed-off-by: Alessandro Comodi --- docs/.gitignore | 4 ++-- docs/Makefile | 18 +++++++++--------- .../architecture/bitstream_format.rst | 0 docs/architecture/code_of_conduct.md | 1 + docs/{src => }/architecture/configuration.rst | 0 docs/architecture/copying.md | 1 + .../architecture/dram_configuration.rst | 0 docs/{src => }/architecture/glossary.rst | 0 docs/{src => }/architecture/interconnect.rst | 0 docs/{src => }/architecture/overview.rst | 0 docs/{src => }/architecture/reference.rst | 0 docs/architecture/updating_the_docs.md | 1 + docs/conf.py | 2 +- docs/db_dev_process/contributing.md | 1 + docs/db_dev_process/fuzzers/index | 1 + .../{src => }/db_dev_process/fuzzers/index.rst | 0 docs/db_dev_process/minitests/index | 1 + .../db_dev_process/minitests/index.rst | 1 - docs/{src => }/db_dev_process/parts.rst | 0 docs/db_dev_process/readme.md | 1 + docs/{src => }/format/db.rst | 0 docs/{src => }/format/tile.rst | 0 docs/{src => }/index.rst | 0 docs/src/architecture/code_of_conduct.md | 1 - docs/src/architecture/copying.md | 1 - docs/src/architecture/updating_the_docs.md | 1 - docs/src/db_dev_process/contributing.md | 1 - docs/src/db_dev_process/fuzzers/index | 1 - docs/src/db_dev_process/minitests/index | 1 - docs/src/db_dev_process/readme.md | 1 - 30 files changed, 19 insertions(+), 20 deletions(-) rename docs/{src => }/architecture/bitstream_format.rst (100%) create mode 120000 docs/architecture/code_of_conduct.md rename docs/{src => }/architecture/configuration.rst (100%) create mode 120000 docs/architecture/copying.md rename docs/{src => }/architecture/dram_configuration.rst (100%) rename docs/{src => }/architecture/glossary.rst (100%) rename docs/{src => }/architecture/interconnect.rst (100%) rename docs/{src => }/architecture/overview.rst (100%) rename docs/{src => }/architecture/reference.rst (100%) create mode 120000 docs/architecture/updating_the_docs.md create mode 120000 docs/db_dev_process/contributing.md create mode 120000 docs/db_dev_process/fuzzers/index rename docs/{src => }/db_dev_process/fuzzers/index.rst (100%) create mode 120000 docs/db_dev_process/minitests/index rename docs/{src => }/db_dev_process/minitests/index.rst (97%) rename docs/{src => }/db_dev_process/parts.rst (100%) create mode 120000 docs/db_dev_process/readme.md rename docs/{src => }/format/db.rst (100%) rename docs/{src => }/format/tile.rst (100%) rename docs/{src => }/index.rst (100%) delete mode 120000 docs/src/architecture/code_of_conduct.md delete mode 120000 docs/src/architecture/copying.md delete mode 120000 docs/src/architecture/updating_the_docs.md delete mode 120000 docs/src/db_dev_process/contributing.md delete mode 120000 docs/src/db_dev_process/fuzzers/index delete mode 120000 docs/src/db_dev_process/minitests/index delete mode 120000 docs/src/db_dev_process/readme.md diff --git a/docs/.gitignore b/docs/.gitignore index c8d939ef..9d7ce536 100644 --- a/docs/.gitignore +++ b/docs/.gitignore @@ -1,3 +1,3 @@ _build -src/db_dev_process/fuzzers/*.md -src/db_dev_process/minitests/*.md +db_dev_process/fuzzers/*.md +db_dev_process/minitests/*.md diff --git a/docs/Makefile b/docs/Makefile index 02bebc6c..d845e77b 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -8,7 +8,7 @@ SPHINXOPTS = SPHINXBUILD = sphinx-build SPHINXAUTOBUILD = sphinx-autobuild SPHINXPROJ = ProjectX-Ray -SOURCEDIR = src +SOURCEDIR = . BUILDDIR = _build # Put it first so that "make" without argument is like "make help". @@ -22,10 +22,10 @@ livehtml: # Update fuzzer / minitest markdown links. fuzzers-links: - @mkdir -p $(MAKEDIR)/${SOURCEDIR}/db_dev_process/fuzzers - @cd $(MAKEDIR)/${SOURCEDIR}/db_dev_process/fuzzers && rm -f *.md - @cd $(MAKEDIR)/${SOURCEDIR}/db_dev_process/fuzzers && \ - for i in ../../../../fuzzers/*; do \ + @mkdir -p $(MAKEDIR)/db_dev_process/fuzzers + @cd $(MAKEDIR)/db_dev_process/fuzzers && rm -f *.md + @cd $(MAKEDIR)/db_dev_process/fuzzers && \ + for i in ../../../fuzzers/*; do \ n=$$(basename $$i | sed -e's/^[0-9][0-9][0-9]-//'); \ if [ ! -d $$i ]; then \ continue; \ @@ -42,10 +42,10 @@ fuzzers-links: done minitests-links: - @mkdir -p $(MAKEDIR)/${SOURCEDIR}/db_dev_process/minitests - @cd $(MAKEDIR)/${SOURCEDIR}/db_dev_process/minitests && rm -f *.md - @cd $(MAKEDIR)/${SOURCEDIR}/db_dev_process/minitests && \ - for i in ../../../../minitests/*; do \ + @mkdir -p $(MAKEDIR)/db_dev_process/minitests + @cd $(MAKEDIR)/db_dev_process/minitests && rm -f *.md + @cd $(MAKEDIR)/db_dev_process/minitests && \ + for i in ../../../minitests/*; do \ n=$$(basename $$i | sed -e's/^[0-9][0-9][0-9]-//'); \ if [ ! -d $$i ]; then \ continue; \ diff --git a/docs/src/architecture/bitstream_format.rst b/docs/architecture/bitstream_format.rst similarity index 100% rename from docs/src/architecture/bitstream_format.rst rename to docs/architecture/bitstream_format.rst diff --git a/docs/architecture/code_of_conduct.md b/docs/architecture/code_of_conduct.md new file mode 120000 index 00000000..a3613c99 --- /dev/null +++ b/docs/architecture/code_of_conduct.md @@ -0,0 +1 @@ +../../CODE_OF_CONDUCT.md \ No newline at end of file diff --git a/docs/src/architecture/configuration.rst b/docs/architecture/configuration.rst similarity index 100% rename from docs/src/architecture/configuration.rst rename to docs/architecture/configuration.rst diff --git a/docs/architecture/copying.md b/docs/architecture/copying.md new file mode 120000 index 00000000..7d29222e --- /dev/null +++ b/docs/architecture/copying.md @@ -0,0 +1 @@ +../../COPYING \ No newline at end of file diff --git a/docs/src/architecture/dram_configuration.rst b/docs/architecture/dram_configuration.rst similarity index 100% rename from docs/src/architecture/dram_configuration.rst rename to docs/architecture/dram_configuration.rst diff --git a/docs/src/architecture/glossary.rst b/docs/architecture/glossary.rst similarity index 100% rename from docs/src/architecture/glossary.rst rename to docs/architecture/glossary.rst diff --git a/docs/src/architecture/interconnect.rst b/docs/architecture/interconnect.rst similarity index 100% rename from docs/src/architecture/interconnect.rst rename to docs/architecture/interconnect.rst diff --git a/docs/src/architecture/overview.rst b/docs/architecture/overview.rst similarity index 100% rename from docs/src/architecture/overview.rst rename to docs/architecture/overview.rst diff --git a/docs/src/architecture/reference.rst b/docs/architecture/reference.rst similarity index 100% rename from docs/src/architecture/reference.rst rename to docs/architecture/reference.rst diff --git a/docs/architecture/updating_the_docs.md b/docs/architecture/updating_the_docs.md new file mode 120000 index 00000000..32e89853 --- /dev/null +++ b/docs/architecture/updating_the_docs.md @@ -0,0 +1 @@ +../../UPDATING-THE-DOCS.md \ No newline at end of file diff --git a/docs/conf.py b/docs/conf.py index 7137c4a2..3761d887 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -200,7 +200,7 @@ def setup(app): github_code_branch = 'blob/master/' docs_root_dir = os.path.realpath(os.path.dirname(__file__)) - code_root_dir = os.path.realpath(os.path.join(docs_root_dir, "..", "..")) + code_root_dir = os.path.realpath(os.path.join(docs_root_dir, "..")) MarkdownSymlinksDomain.init_domain( github_code_repo, github_code_branch, docs_root_dir, code_root_dir) diff --git a/docs/db_dev_process/contributing.md b/docs/db_dev_process/contributing.md new file mode 120000 index 00000000..f939e75f --- /dev/null +++ b/docs/db_dev_process/contributing.md @@ -0,0 +1 @@ +../../CONTRIBUTING.md \ No newline at end of file diff --git a/docs/db_dev_process/fuzzers/index b/docs/db_dev_process/fuzzers/index new file mode 120000 index 00000000..76076bf2 --- /dev/null +++ b/docs/db_dev_process/fuzzers/index @@ -0,0 +1 @@ +../../../fuzzers/ \ No newline at end of file diff --git a/docs/src/db_dev_process/fuzzers/index.rst b/docs/db_dev_process/fuzzers/index.rst similarity index 100% rename from docs/src/db_dev_process/fuzzers/index.rst rename to docs/db_dev_process/fuzzers/index.rst diff --git a/docs/db_dev_process/minitests/index b/docs/db_dev_process/minitests/index new file mode 120000 index 00000000..40e60221 --- /dev/null +++ b/docs/db_dev_process/minitests/index @@ -0,0 +1 @@ +../../../minitests/ \ No newline at end of file diff --git a/docs/src/db_dev_process/minitests/index.rst b/docs/db_dev_process/minitests/index.rst similarity index 97% rename from docs/src/db_dev_process/minitests/index.rst rename to docs/db_dev_process/minitests/index.rst index 2e06adb6..d97f6ba8 100644 --- a/docs/src/db_dev_process/minitests/index.rst +++ b/docs/db_dev_process/minitests/index.rst @@ -14,7 +14,6 @@ Minitests are experiments to figure out how things work. They allow us to unders clkbuf eccbits fixedpnr - index.rst litex lvb_long_mux nodes_wires_list diff --git a/docs/src/db_dev_process/parts.rst b/docs/db_dev_process/parts.rst similarity index 100% rename from docs/src/db_dev_process/parts.rst rename to docs/db_dev_process/parts.rst diff --git a/docs/db_dev_process/readme.md b/docs/db_dev_process/readme.md new file mode 120000 index 00000000..fe840054 --- /dev/null +++ b/docs/db_dev_process/readme.md @@ -0,0 +1 @@ +../../README.md \ No newline at end of file diff --git a/docs/src/format/db.rst b/docs/format/db.rst similarity index 100% rename from docs/src/format/db.rst rename to docs/format/db.rst diff --git a/docs/src/format/tile.rst b/docs/format/tile.rst similarity index 100% rename from docs/src/format/tile.rst rename to docs/format/tile.rst diff --git a/docs/src/index.rst b/docs/index.rst similarity index 100% rename from docs/src/index.rst rename to docs/index.rst diff --git a/docs/src/architecture/code_of_conduct.md b/docs/src/architecture/code_of_conduct.md deleted file mode 120000 index 5d525cd1..00000000 --- a/docs/src/architecture/code_of_conduct.md +++ /dev/null @@ -1 +0,0 @@ -../../../CODE_OF_CONDUCT.md \ No newline at end of file diff --git a/docs/src/architecture/copying.md b/docs/src/architecture/copying.md deleted file mode 120000 index 28b80bcc..00000000 --- a/docs/src/architecture/copying.md +++ /dev/null @@ -1 +0,0 @@ -../../../COPYING \ No newline at end of file diff --git a/docs/src/architecture/updating_the_docs.md b/docs/src/architecture/updating_the_docs.md deleted file mode 120000 index 22d86c5d..00000000 --- a/docs/src/architecture/updating_the_docs.md +++ /dev/null @@ -1 +0,0 @@ -../../../UPDATING-THE-DOCS.md \ No newline at end of file diff --git a/docs/src/db_dev_process/contributing.md b/docs/src/db_dev_process/contributing.md deleted file mode 120000 index c97564d9..00000000 --- a/docs/src/db_dev_process/contributing.md +++ /dev/null @@ -1 +0,0 @@ -../../../CONTRIBUTING.md \ No newline at end of file diff --git a/docs/src/db_dev_process/fuzzers/index b/docs/src/db_dev_process/fuzzers/index deleted file mode 120000 index d78a6674..00000000 --- a/docs/src/db_dev_process/fuzzers/index +++ /dev/null @@ -1 +0,0 @@ -../../../../fuzzers/ \ No newline at end of file diff --git a/docs/src/db_dev_process/minitests/index b/docs/src/db_dev_process/minitests/index deleted file mode 120000 index 353e56d0..00000000 --- a/docs/src/db_dev_process/minitests/index +++ /dev/null @@ -1 +0,0 @@ -../../../../minitests/ \ No newline at end of file diff --git a/docs/src/db_dev_process/readme.md b/docs/src/db_dev_process/readme.md deleted file mode 120000 index 8a33348c..00000000 --- a/docs/src/db_dev_process/readme.md +++ /dev/null @@ -1 +0,0 @@ -../../../README.md \ No newline at end of file From 2fab112c7195b163bfeecbec8b804b5da2ef0d34 Mon Sep 17 00:00:00 2001 From: Alessandro Comodi Date: Wed, 25 Sep 2019 09:54:28 +0200 Subject: [PATCH 11/11] docs: fixed some READMEs and removed empty .md file generation Signed-off-by: Alessandro Comodi --- docs/Makefile | 6 ------ minitests/partial_reconfig_flow/README.md | 4 ++-- minitests/roi_harness/README.md | 4 ++-- minitests/timing/README.md | 4 ++-- 4 files changed, 6 insertions(+), 12 deletions(-) diff --git a/docs/Makefile b/docs/Makefile index d845e77b..3028a5bd 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -35,9 +35,6 @@ fuzzers-links: ln -s $$i/README.md $${n}.md; \ else \ echo "Missing $$i/README.md"; \ - echo "# $$n Fuzzer" > $${n}.md; \ - echo "" >> $${n}.md; \ - echo "Missing README.md!" >> $${n}.md; \ fi; \ done @@ -55,9 +52,6 @@ minitests-links: ln -s $$i/README.md $${n}.md; \ else \ echo "Missing $$i/README.md"; \ - echo "# $$n Minitest" > $${n}.md; \ - echo "" >> $${n}.md; \ - echo "Missing README.md!" >> $${n}.md; \ fi; \ done diff --git a/minitests/partial_reconfig_flow/README.md b/minitests/partial_reconfig_flow/README.md index 930ac9b4..1cb8ca2b 100644 --- a/minitests/partial_reconfig_flow/README.md +++ b/minitests/partial_reconfig_flow/README.md @@ -10,7 +10,7 @@ harness into a bitstream with fasm2frame and xc7patch. Since writting FASM is rather tedious, rules are provided to convert Verilog ROI designs into FASM via Vivado. -# Usage +## Usage make rules are provided for generating each step of the process so that intermediate forms can be analyzed. Assuming you have a .fasm file, invoking @@ -20,7 +20,7 @@ the %\_hand\_crafted.bit rule will generate a merged bitstream: make foo.hand\_crafted.bit # reads foo.fasm ``` -# Using Vivado to generate .fasm +## Using Vivado to generate .fasm Vivado's Partial Reconfiguration flow can be used to synthesize and implement a ROI design that is then converted to .fasm. Write a Verilog module diff --git a/minitests/roi_harness/README.md b/minitests/roi_harness/README.md index 4c0841cd..9c1db89a 100644 --- a/minitests/roi_harness/README.md +++ b/minitests/roi_harness/README.md @@ -81,7 +81,7 @@ The following configurations are supported; # 125 MHz CLK onboard K17 -# Quickstart +## Quickstart ``` source settings/artix7.sh @@ -91,7 +91,7 @@ make clean make copy ``` -# How it works +## How it works Basic idea: - LOC LUTs in the ROI to terminate input and output routing diff --git a/minitests/timing/README.md b/minitests/timing/README.md index 5d5a8543..e707ef7f 100644 --- a/minitests/timing/README.md +++ b/minitests/timing/README.md @@ -13,14 +13,14 @@ comparision between the reduced model implemented in prjxray and the Vivado timing results. Model quality -============= +------------- The prjxray timing handles most nets +/- 1.5% delay. The large exception to this is clock nets, which appear to use a table lookup that is not understood at this time. Running the model -================= +----------------- The provided Makefile will by default compile all examples. It a specific design family is desired, the family name can be provided. If a specific design within