Update documentation for clock examples #42

daniellimws · 2020-04-15T12:58:18Z

This adds many examples from the tests/clocks directory to the documentation, including the verilog code with a svg generated from it, and the contents of their respective model.xml.

mithro · 2020-04-15T18:32:00Z

@daniellimws This looks pretty good!

mithro · 2020-04-15T22:33:22Z

@daniellimws - If you rebase and force push this branch there should be a new read-the-docs build that generates a preview of your new output!

daniellimws · 2020-04-16T01:37:29Z

I'm currently following the naming that was given earlier in the docs. In this example, the title is "D-Flipflop with combinational logic". Doesn't a D-flipflop only have input D and output Q? Should we rename this to just flipflop instead of D-flipflop?

daniellimws · 2020-04-16T11:19:47Z

There are many black box modules in the examples. As a result, netlistsvg renders them as ports not connected to any module (for example this).

Should we use the designs generated by symbolator for such cases (like this)? Might have some inconsistency in the designs? Any ideas?

mithro · 2020-04-16T17:49:43Z

@daniellimws - Regarding the weird rendering from the netlistsvg output I logged #48

mithro · 2020-04-16T18:30:17Z

I also logged - #50 -- Come up with a good "template" for documentation of the tests

I think all the tests should have both symbolator diagram of the verilog and netlistsvg rendered output.

daniellimws · 2020-04-17T07:30:05Z

docs/conf.py

@@ -45,6 +45,7 @@
    'sphinx_markdown_tables',
    'symbolator_sphinx',
    'sphinxcontrib_verilog_diagrams',
+    'm2r'


@mithro I'm using this extension to convert markdown into rst so that we can directly include README.md into the home page index.rst. However, there is a bug with the current version of m2r installed from pip/conda. I've applied the fix suggested here to my own fork. May I transfer it to SymbiFlow for sustainability purposes?

Also, this causes the readthedocs build to fail for now because of these lines https://github.com/SymbiFlow/python-symbiflow-v2x/pull/42/files#diff-85987f48f1258d9ee486e3191495582dR57-R59 causing there to be two markdown source parsers (when there should only be one).

I think we need to figure out if we want to use m2r or recommonmark modules in all our documentation. This probably is a discussion for IRC.

Another option is to convert the README.md to a README.rst at the top level. Both PyPi and GitHub can reader rst files.

mithro · 2020-04-17T18:01:18Z

README.md

@@ -1,9 +1,106 @@
-# python-symbiflow-v2x
+# SymbiFlow Verilog to XML


I think we want to be clear it is "Verilog to Routing XML", however "SymbiFlow Verilog to Verilog to Routing XML" is super weird looking with multiple "Verilog to" in it....

Maybe the following? Open to alternatives;

Suggested change

# SymbiFlow Verilog to XML

# Verilog to Routing XML file generation from Verilog (`python-symbiflow-v2x`)

Alright changed. I thought I changed this, maybe lost it when rebasing.

Still doesn't seem to have updated?

Oh! The issue is you have a README.rst and a README.md file now!

Oh I forgot about it. I changed to use README.rst in the other pull request.

daniellimws · 2020-04-19T12:04:45Z

Addressed #47, #49, (hopefully) #50, and additionally #54. #50 too(?) if we are fine with omitting the netlistsvg diagram, showing only the symbolator diagram for blackbox modules.

mithro · 2020-04-20T14:01:13Z

@daniellimws Could you move Use README.rst instead of README.md into it's own pull request?

mithro · 2020-04-20T17:37:38Z

Please rebase onto master. I think it LGTM otherwise.

daniellimws · 2020-04-21T01:11:40Z

Ok, rebased and squashed some commits.

daniellimws · 2020-04-26T03:26:56Z

@mithro I just realized I didn't add the linenos option to show the line numbers next to the code. What do you think? Do we want to have that?

daniellimws · 2020-04-26T03:50:55Z

There are many black box modules in the tests, which have the (* whitebox *) attribute. For example:

/*
 * `input wire a` should be detected as a clock because of the `(* CLOCK *)`
 * attribute.
 */
(* whitebox *)
module BLOCK(a, b, o);
	(* CLOCK *)
	input wire a;
	input wire b;
	output wire o;
endmodule

I think the documentation should give a brief explanation on why there is a (* whitebox *) attribute, what is the reason to put this there. Perhaps this could be done on it's own page so that we don't repeat it everywhere (in a separate issue/PR).

(Actually, I myself don't know why is that attribute included.)

mithro · 2020-04-26T18:17:45Z

@daniellimws - I created #61 to track the documentation of the whitebox attributes and friends.

mithro

Just the two minor comments.

Signed-off-by: Daniel Lim Wee Soong <[email protected]>

- Rename docs/tests/ to docs/examples/ as it fits the content more closely - Add examples main page - Add description for clock examples page Signed-off-by: Daniel Lim Wee Soong <[email protected]>

Signed-off-by: Daniel Lim Wee Soong <[email protected]>

daniellimws · 2020-04-27T03:44:31Z

Ok removed README.md

tests/clocks/input_attr_not_clock/README.rst

All this while it was using `code` which italicizes the code instead of ``code``. Signed-off-by: Daniel Lim Wee Soong <[email protected]>

mithro · 2020-04-30T23:59:43Z

@daniellimws - We seem to have lost a bunch of the documentation?

Compare https://python-symbiflow-v2x.readthedocs.io/en/latest/ to https://python-symbiflow-v2x--42.org.readthedocs.build/en/42/index.html

The left side is just showing "examples" now. Clicking on the "DSP" under the examples gets an empty page.

SymbiFlow Verilog to VtR XML (v2x) — SymbiFlow Verilog to XML (V2X) 0.0-477-g4cce797 documentation

Verilog to Routing XML file generation from Verilog (python-symbiflow-v2x) — SymbiFlow Verilog to XML (V2X) 0.0-487-gea2317b documentation

Signed-off-by: Daniel Lim Wee Soong <[email protected]>

daniellimws · 2020-05-01T02:46:48Z

The problem was make links outputs to tests while I have changed the directory name to examples/.

Another problem was that the rtd build for master uses sphinx 2.4.4 while the build for this pull request uses sphinx 3.0.3. The newer version complains that the md files do not have a title and refuses to add them to the toctree.

To fix this I changed the environment.yml file to use sphinx 2.4.4 for now while we are still using the markdown symlinks. Also removed breathe from requirements.txt because we aren't using it and it only works on sphinx version 3.

The build for this PR still doesn't show the DSP examples because it is still using sphinx 3.0.3. I think it would work in master however.

daniellimws · 2020-05-20T10:51:10Z

@mithro Ok to merge?

kgugala · 2020-05-20T19:44:03Z

docs/examples.rst

@@ -0,0 +1,10 @@
+Examples
+============


this underline is too long

kgugala · 2020-05-20T19:44:12Z

docs/examples/clocks.rst

+.. Clock Example Tests
+
+Clock
+==============


this underline is too long

kgugala · 2020-05-20T19:44:19Z

docs/examples/clocks/autodetection.rst

@@ -0,0 +1,6 @@
+Autodetection of clock from flipflop
+=====================================


this underline is too long

kgugala · 2020-05-20T19:44:25Z

docs/examples/clocks/manual_input.rst

@@ -0,0 +1,7 @@
+Manually set inputs as clock
+==================================


this underline is too long

kgugala · 2020-05-20T19:44:32Z

docs/examples/clocks/manual_output.rst

@@ -0,0 +1,5 @@
+Manually set outputs as clock
+==================================


this underline is too long

kgugala · 2020-05-20T19:48:19Z

tests/clocks/input_named_clk/README.rst

@@ -0,0 +1,19 @@
+Set input as clock by name (clk)
+++++++++++++++++++++++++++++++++++


this underline is too long

kgugala · 2020-05-20T19:48:27Z

tests/clocks/input_named_regex/README.rst

@@ -0,0 +1,23 @@
+Set input as clock by name (regex)
+++++++++++++++++++++++++++++++++++


this underline is too long

kgugala · 2020-05-20T19:48:39Z

tests/clocks/multiple_outputs_named_clk/README.rst

@@ -0,0 +1,19 @@
+Set outputs as clock by name (multiple clock outputs)
++++++++++++++++++++++++++++++++++++++++++++++++++++++


this underline is too long

kgugala · 2020-05-20T19:48:55Z

tests/clocks/output_attr_clock/README.rst

@@ -0,0 +1,19 @@
+Manually set output as clock by setting the CLOCK attribute
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++


this underline is too long

kgugala · 2020-05-20T19:49:01Z

tests/clocks/output_named_clk/README.rst

@@ -0,0 +1,19 @@
+Set output as clock by name (clk)
+++++++++++++++++++++++++++++++++++


this underline is too long

daniellimws · 2020-05-21T00:57:21Z

Ok fixed the underlines

Signed-off-by: Daniel Lim Wee Soong <[email protected]>

daniellimws · 2020-05-21T02:23:09Z

Weird. flake8 is failing on a file I did not modify.

mithro requested review from mkurc-ant, mithro and kgugala April 15, 2020 17:36

daniellimws force-pushed the docs-clock branch from bc93ac6 to 55c66bf Compare April 16, 2020 02:56

daniellimws commented Apr 17, 2020

View reviewed changes

daniellimws force-pushed the docs-clock branch 3 times, most recently from 4cec9de to 0adcea7 Compare April 17, 2020 13:22

mithro reviewed Apr 17, 2020

View reviewed changes

daniellimws force-pushed the docs-clock branch 2 times, most recently from 4c95c47 to de0d892 Compare April 19, 2020 09:12

daniellimws force-pushed the docs-clock branch from de0d892 to 2f24549 Compare April 19, 2020 12:06

daniellimws force-pushed the docs-clock branch 2 times, most recently from 0735423 to 2960694 Compare April 21, 2020 01:09

daniellimws mentioned this pull request Apr 21, 2020

Add link to examples in README SymbiFlow/sphinxcontrib-hdl-diagrams#18

Merged

daniellimws force-pushed the docs-clock branch from 69465a8 to d5b2ce1 Compare April 21, 2020 02:54

mithro mentioned this pull request Apr 26, 2020

Document the (* whitebox *) (and related attribute) #61

Open

mithro approved these changes Apr 27, 2020

View reviewed changes

daniellimws added 8 commits April 27, 2020 11:05

Update documentation for clock examples

ae2d34b

Signed-off-by: Daniel Lim Wee Soong <[email protected]>

Update file names and xml attributes to follow convention

fdde5a8

Signed-off-by: Daniel Lim Wee Soong <[email protected]>

Allow make livehtml to watch for changes in tests/

9e518ea

Signed-off-by: Daniel Lim Wee Soong <[email protected]>

Add verilog-diagram to the examples

531dc81

Signed-off-by: Daniel Lim Wee Soong <[email protected]>

docs: Rearrange layout

458d413

- Rename docs/tests/ to docs/examples/ as it fits the content more closely - Add examples main page - Add description for clock examples page Signed-off-by: Daniel Lim Wee Soong <[email protected]>

Hide copyright from verilog code

6968a92

Signed-off-by: Daniel Lim Wee Soong <[email protected]>

Remove netlistsvg diagram for blackbox modules and add pb_type.xml

feab218

Signed-off-by: Daniel Lim Wee Soong <[email protected]>

Change README title

a3d9037

Signed-off-by: Daniel Lim Wee Soong <[email protected]>

daniellimws force-pushed the docs-clock branch from ab5c6f3 to a3d9037 Compare April 27, 2020 03:06

Remove README.md as we decided to use README.rst in chipsalliance#57

b989576

Signed-off-by: Daniel Lim Wee Soong <[email protected]>

mithro reviewed Apr 27, 2020

View reviewed changes

tests/clocks/input_attr_not_clock/README.rst Show resolved Hide resolved

Fix inline code blocks formatting

ea2317b

All this while it was using `code` which italicizes the code instead of ``code``. Signed-off-by: Daniel Lim Wee Soong <[email protected]>

daniellimws force-pushed the docs-clock branch from 5373101 to ea2317b Compare April 27, 2020 06:16

daniellimws added 2 commits May 1, 2020 10:35

Fix make links to output to docs/examples

299ba27

Signed-off-by: Daniel Lim Wee Soong <[email protected]>

Use sphinx version 2.4.4 for markdown links to work

9b64e85

Signed-off-by: Daniel Lim Wee Soong <[email protected]>

daniellimws force-pushed the docs-clock branch from c46ae12 to 9b64e85 Compare May 1, 2020 02:41

kgugala requested changes May 20, 2020

View reviewed changes

daniellimws added 2 commits May 21, 2020 09:00

Fix underline length

0b6c964

Signed-off-by: Daniel Lim Wee Soong <[email protected]>

Revert unnecessary change in golden model

722bf49

Signed-off-by: Daniel Lim Wee Soong <[email protected]>

daniellimws force-pushed the docs-clock branch from b492fb9 to 722bf49 Compare May 21, 2020 01:00

mithro approved these changes Jun 16, 2020

View reviewed changes

mithro merged commit 5a8fb0d into chipsalliance:master Jun 16, 2020

daniellimws mentioned this pull request Jul 16, 2020

docs: Show all READMEs from the tests in the docs #71

Closed

		@@ -1,9 +1,106 @@
		# python-symbiflow-v2x
		# SymbiFlow Verilog to XML

	# SymbiFlow Verilog to XML
	# Verilog to Routing XML file generation from Verilog (`python-symbiflow-v2x`)

		@@ -0,0 +1,6 @@
		Autodetection of clock from flipflop
		=====================================

		@@ -0,0 +1,7 @@
		Manually set inputs as clock
		==================================

		@@ -0,0 +1,5 @@
		Manually set outputs as clock
		==================================

		@@ -0,0 +1,19 @@
		Set input as clock by name (clk)
		+++++++++++++++++++++++++++++++++++

		@@ -0,0 +1,23 @@
		Set input as clock by name (regex)
		+++++++++++++++++++++++++++++++++++

		@@ -0,0 +1,19 @@
		Set outputs as clock by name (multiple clock outputs)
		++++++++++++++++++++++++++++++++++++++++++++++++++++++

		@@ -0,0 +1,19 @@
		Manually set output as clock by setting the CLOCK attribute
		++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++

		@@ -0,0 +1,19 @@
		Set output as clock by name (clk)
		+++++++++++++++++++++++++++++++++++

		@@ -0,0 +1,10 @@
		Examples
		============

Update documentation for clock examples #42

Update documentation for clock examples #42

Conversation

daniellimws commented Apr 15, 2020

mithro commented Apr 15, 2020

mithro commented Apr 15, 2020

daniellimws commented Apr 16, 2020

daniellimws commented Apr 16, 2020

mithro commented Apr 16, 2020

mithro commented Apr 16, 2020

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

daniellimws commented Apr 19, 2020

mithro commented Apr 20, 2020

mithro commented Apr 20, 2020

daniellimws commented Apr 21, 2020

daniellimws commented Apr 26, 2020

daniellimws commented Apr 26, 2020

mithro commented Apr 26, 2020

mithro left a comment

Choose a reason for hiding this comment

daniellimws commented Apr 27, 2020

mithro commented Apr 30, 2020 • edited by unfurl-links bot Loading

daniellimws commented May 1, 2020 • edited Loading

daniellimws commented May 20, 2020

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

daniellimws commented May 21, 2020

daniellimws commented May 21, 2020

mithro commented Apr 30, 2020 •

edited by unfurl-links bot

Loading

daniellimws commented May 1, 2020 •

edited

Loading