Merge pull request #41 from daniellimws/docs-portability Allow docs/Makefile to be portable
diff --git a/README.md b/README.md index 37dac98..eceb48e 100644 --- a/README.md +++ b/README.md
@@ -7,3 +7,93 @@ Documentation can be found at https://python-symbiflow-v2x.readthedocs.io/en/latest/ +## Installation +v2x can be installed from a local git repository using pip. + +``` +cd python-symbiflow-v2x +pip install . +``` + +Alternatively, it can be installed from GitHub directly. + +``` +pip install git+https://github.com/SymbiFlow/python-symbiflow-v2x.git +``` + +## Usage +After installing v2x, you can run `v2x` to use it. + +``` +v2x -h +usage: __main__.py [-h] [--top TOP] [--outfile OUTFILE] [--includes INCLUDES] + [--mode {pb_type,model}] + input.v [input.v ...] + +Verilog to XML + +positional arguments: + input.v One or more Verilog input files, that will be passed + to Yosys internally. They should be enough to generate + a flattened representation of the model, so that paths + through the model can be determined. + +optional arguments: + -h, --help show this help message and exit + --top TOP Top level module, will usually be automatically + determined from the file name im.v + --outfile OUTFILE, -o OUTFILE + Output filename, default 'output.xml' + --includes INCLUDES Comma separate list of include directories. + --mode {pb_type,model} + Output file type, possible values are: pb_type and + model. Default value is pb_type +``` + +For example, to generate a pb_type xml file from adder.v, run + +``` +v2x -o adder.pb_type.xml adder.v +``` + +Or, to generate a model xml file, run + +``` +v2x --mode model -o adder.model.xml adder.v +``` + +v2x expects the module name to be the same as the file name. If it is different, make sure to specifiy it with the `--top` argument. + +``` +v2x --top BLOCK -o adder.pb_type.xml adder.v +``` + +## Tests +The test cases are stored in tests/, and pytest can be used to run them. + +``` +rm -rf build # run this step so that pytest uses the latest files for the tests +pytest -vv +``` + +If you are making changes to any python code, make sure that they follow the PEP8 style guide by running flake8. + +``` +flake8 tests +flake8 v2x +``` + +## Documentation +We use sphinx for our documentation and the files are stored in docs/. To host it locally (if you are planning to update it), you can use the Makefile inside. + +First, run `make env` to prepare a Conda environment that contains the necessary packages to build and host the documentation site. After that, simply run `make livehtml` which starts a local server running at port 8000 with the documentation site. + +``` +cd docs +make env +make livehtml +``` + +## Talks + +[](https://www.youtube.com/watch?v=a31vH_tZLBM) \ No newline at end of file
diff --git a/README.rst b/README.rst new file mode 100644 index 0000000..b2a5f86 --- /dev/null +++ b/README.rst
@@ -0,0 +1,123 @@ +SymbiFlow Verilog to VtR XML (v2x) +=================================== + + +.. image:: https://readthedocs.org/projects/python-symbiflow-v2x/badge/?version=latest + :target: https://python-symbiflow-v2x.readthedocs.io/en/latest/?badge=latest + :alt: Documentation Status + +.. image:: https://travis-ci.com/SymbiFlow/python-symbiflow-v2x.svg?branch=master + :target: https://travis-ci.com/SymbiFlow/python-symbiflow-v2x + :alt: Build Status + + +v2x is a tool for converting specialized annotated Verilog models into XML needed for +`Verilog to Routing flow <https://docs.verilogtorouting.org/en/latest/arch/reference/>`_. + +Documentation can be found at `https://python-symbiflow-v2x.readthedocs.io/en/latest/ <https://python-symbiflow-v2x.readthedocs.io/en/latest/examples.html>`_. + +Installation +------------ + +v2x can be installed from a local git repository using pip. + +.. code-block:: + + cd python-symbiflow-v2x + pip install . + +Alternatively, it can be installed from GitHub directly. + +.. code-block:: + + pip install git+https://github.com/SymbiFlow/python-symbiflow-v2x.git#egg=python-symbiflow-v2x + +Usage +----- + +After installing v2x, you can run ``v2x`` to use it. + +.. code-block:: + + v2x -h + usage: __main__.py [-h] [--top TOP] [--outfile OUTFILE] [--includes INCLUDES] + [--mode {pb_type,model}] + input.v [input.v ...] + + Verilog to XML + + positional arguments: + input.v One or more Verilog input files, that will be passed + to Yosys internally. They should be enough to generate + a flattened representation of the model, so that paths + through the model can be determined. + + optional arguments: + -h, --help show this help message and exit + --top TOP Top level module, will usually be automatically + determined from the file name im.v + --outfile OUTFILE, -o OUTFILE + Output filename, default 'output.xml' + --includes INCLUDES Comma separate list of include directories. + --mode {pb_type,model} + Output file type, possible values are: pb_type and + model. Default value is pb_type + +For example, to generate a pb_type xml file from adder.v, run + +.. code-block:: + + v2x -o adder.pb_type.xml adder.v + +Or, to generate a model xml file, run + +.. code-block:: + + v2x --mode model -o adder.model.xml adder.v + +v2x expects the module name to be the same as the file name. If it is different, make sure to specifiy it with the ``--top`` argument. + +.. code-block:: + + v2x --top BLOCK -o adder.pb_type.xml adder.v + +Tests +----- + +The test cases are stored in tests/, and pytest can be used to run them. + +.. code-block:: + + rm -rf build # run this step so that pytest uses the latest files for the tests + pytest -vv + +If you are making changes to any python code, make sure that they follow the PEP8 style guide by running flake8. + +.. code-block:: + + flake8 tests + flake8 v2x + +Documentation +------------- + +We use sphinx for our documentation and the files are stored in docs/. To host it locally (if you are planning to update it), you can use the Makefile inside. + +First, run ``make env`` to prepare a Conda environment that contains the necessary packages to build and host the documentation site. After that, simply run ``make livehtml`` which starts a local server running at port 8000 with the documentation site. + +.. code-block:: + + cd docs + make env + make livehtml + +Talks +----- + +**VPR device models generation from Verilog with V2X - Karol Gugala - ORConf 2019** + + +.. image:: https://img.youtube.com/vi/a31vH_tZLBM/0.jpg + :target: https://www.youtube.com/watch?v=a31vH_tZLBM + :alt: v2x orconf talk +
diff --git a/docs/conf.py b/docs/conf.py index e7b7def..ccbda5f 100644 --- a/docs/conf.py +++ b/docs/conf.py
@@ -1,5 +1,14 @@ +#!/usr/bin/env python3 # -*- coding: utf-8 -*- # +# Copyright (C) 2020 The SymbiFlow Authors. +# +# Use of this source code is governed by a ISC-style +# license that can be found in the LICENSE file or at +# https://opensource.org/licenses/ISC +# +# SPDX-License-Identifier: ISC +# # SymbiFlow V2X documentation build configuration file, created by # sphinx-quickstart on Mon Feb 5 11:04:37 2018. # @@ -44,7 +53,7 @@ 'sphinx.ext.todo', 'sphinx_markdown_tables', 'symbolator_sphinx', - 'sphinxcontrib_verilog_diagrams', + 'sphinxcontrib_verilog_diagrams' ] # Add any paths that contain templates here, relative to this directory.
diff --git a/docs/index.rst b/docs/index.rst index 802792a..d950667 100644 --- a/docs/index.rst +++ b/docs/index.rst
@@ -1,16 +1,9 @@ -.. SymbiFlow V2X documentation master file - -Welcome to SymbiFlow Verilog to XML -========================================= - -`SymbiFlow Verilog to XML`_ `V2X`_ . - -.. _SymbiFlow Verilog to XML: https://github.com/SymbiFlow/python-symbiflow-v2x -.. _V2X: http://symbiflow-v2x.readthedocs.io/ +.. include:: ../README.rst .. toctree:: :maxdepth: 2 :glob: + :hidden: tests/vtr-examples.rst tests/dsp.rst @@ -18,5 +11,6 @@ .. toctree:: :maxdepth: 3 :glob: + :hidden: - tests/clocks.rst + tests/clocks.rst \ No newline at end of file
diff --git a/docs/requirements.txt b/docs/requirements.txt index 24bda82..fb96629 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt
@@ -13,7 +13,7 @@ git+https://github.com/SymbiFlow/sphinxcontrib-markdown-symlinks.git#egg=markdown_code_symlinks # Verilog diagrams using Yosys + netlistsvg -git+https://github.com/SymbiFlow/sphinxcontrib-verilog-diagrams.git#egg=sphinxcontrib-verilog-diagrams +git+https://github.com/SymbiFlow/sphinxcontrib-verilog-diagrams.git@dca04723ec07209bd7be3e883e780ca9dd4f271e#egg=sphinxcontrib-verilog-diagrams # Module diagrams symbolator
diff --git a/setup.py b/setup.py index fe0b925..cd18169 100644 --- a/setup.py +++ b/setup.py
@@ -1,11 +1,25 @@ +#!/usr/bin/env python3 +# -*- coding: utf-8 -*- +# +# Copyright (C) 2020 The SymbiFlow Authors. +# +# Use of this source code is governed by a ISC-style +# license that can be found in the LICENSE file or at +# https://opensource.org/licenses/ISC +# +# SPDX-License-Identifier: ISC + import setuptools -with open("README.md", "r") as fh: +with open("README.rst", "r") as fh: long_description = fh.read() setuptools.setup( name="v2x", version="0.0.1", + entry_points={ + "console_scripts": ["v2x=v2x.__main__:v2x"] + }, author="SymbiFlow Authors", author_email="symbiflow@lists.librecores.org", description="Python library for generating VPR architecture \
diff --git a/v2x/__main__.py b/v2x/__main__.py index 0a33dce..7978002 100644 --- a/v2x/__main__.py +++ b/v2x/__main__.py
@@ -34,7 +34,7 @@ args.infiles, args.includes, args.top, args.outfile)) -if __name__ == '__main__': +def v2x(): parser = argparse.ArgumentParser( description="Verilog to XML" ) @@ -84,3 +84,7 @@ ) args = parser.parse_args() sys.exit(main(args)) + + +if __name__ == '__main__': + v2x()