Merge pull request #57 from daniellimws/docs-readme
Include README in the docs
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..1ab0142 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -44,7 +44,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/setup.py b/setup.py
index 4206b58..6304a63 100644
--- a/setup.py
+++ b/setup.py
@@ -1,6 +1,6 @@
import setuptools
-with open("README.md", "r") as fh:
+with open("README.rst", "r") as fh:
long_description = fh.read()
setuptools.setup(
