search

chipsalliance / f4pga-v2x

Tool for converting specialized annotated Verilog models into XML needed for Verilog to Routing flow.
https://f4pga-v2x.readthedocs.io/en/latest/
Apache License 2.0
10 stars 12 forks source link

Complete docs #78

Closed mkurc-ant closed 3 years ago

mkurc-ant commented 3 years ago

Continuation of work of https://github.com/SymbiFlow/python-symbiflow-v2x/pull/71

mkurc-ant commented 3 years ago

@mithro I've created a build system that automatically converts V2X test cases to examples for documentation. It works like that:

When the documentation is built, a Python script scans the tests directory for README.rst files. When one is found then it copies the whole test subdirectory to docs/examples. Moreover it runs V2X on all Verilog files found there and stylizes generated XMLs for VPR using vtr-xml-utils. The script is aware of module hierarchy (it scans Verilog includes). This makes the final XMLs complete (no includes) and more compact than the ones that come out of V2X. Note that now golden XMLs are not used for documentation. The examples "toctree" section is also automatically generated by the script basing on discovered README.rst files.

For now I've disabled all currently present examples and added some new, simpler ones under tests/gates. Please tell me whether that documentation generation system is ok. If so I can start adding documentation for existing tests presumably in subsequent PRs.

mkurc-ant commented 3 years ago

@mithro I've fixed conda package dependency issues and added back "VTR examples" documentation to the build system. Could you review?

mithro commented 3 years ago

BTW - I would enable line numbers on the XML files too.

mithro commented 3 years ago

Future addition -- when the test references something, add an include which highlights the referenced item.

mithro commented 3 years ago

The rendered readthedocs output seems to be missing some of the examples? https://python-symbiflow-v2x.readthedocs.io/en/latest/examples.html ?

Examples — SymbiFlow Verilog to XML (V2X) 0.0-511-g3ee8489 documentation
mithro commented 3 years ago

Before

image

After

image

mkurc-ant commented 3 years ago

@mithro I added back missing clock examples.

mithro commented 3 years ago

@mkurc-ant - Using fixed verse floating versions is a complicated trade off. By using floating versions we will discover when dependencies break this code as soon as possible. The later we detect a problem, the more features have been added and code changed making it harder to know what caused the breakage.

If we don't use floating versions we do need to set up an "auto-roll" bot which pushes the version forward automatically. Generally with that approach we would have a floating requirements / environment.yml file and a "locked" version which is generated from the floatin versions with the values updated.

So I guess, if we are going to lock the version then you are committing to creating a system to automatically roll the versions.

mithro commented 3 years ago

@mkurc-ant - The output is also missing the DSP example?

mkurc-ant commented 3 years ago

@mithro In #71 DSP examples were missing as well, the "DSP" in TOC is just a placeholder. I'll add the DSP examples.

Regarding fixing package versions: My point is that I just want to avoid a situation when you suddenly discover that the doc building system is broken because some upstream package got updated. The documentation is built only when a change is made to V2X. So imagine that you have added a feature and built the docs. Then eg. a month (or more) later you want to add another feature and you discover that the docs build system does not work anymore because an upstream package got updated. You are then forced to fix the issue with the build system instead of focusing of the feature functionality. By freezing versions you ensure that the build system will work.

Anyways, I'd rather not focus now on creating an automatic version rolling system so I'll unlock all versions. Hopefully no breaking change has been pushed upstream already.

mithro commented 3 years ago

@mkurc-ant Is this ready to merge? If so, can you please go through and resolve all my comments?

mkurc-ant commented 3 years ago

@mithro I've fixed and resolved them all. Ready to merge.

mithro commented 3 years ago

LGTM!

mithro commented 3 years ago

@mkurc-ant - We should track down why symbolator is generating white backgrounds here. I thought we were using our custom version which should be generating transparent backgrounds by default?

daniellimws commented 3 years ago

@mithro I just realized https://github.com/SymbiFlow/symbolator/pull/1 is not merged yet, that's why it is still generating white backgrounds.

mithro commented 3 years ago

Should be merged now!