167 add readmemd to documentation

README.md

@@ -1,4 +1,4 @@
-# `ucc`: Unitary Compiler Collection
+## `ucc`: Unitary Compiler Collection
 
 [![Repository](https://img.shields.io/badge/GitHub-5C5C5C.svg?logo=github)](https://github.com/unitaryfund/ucc)
 [![Unitary Foundation](https://img.shields.io/badge/Supported%20By-Unitary%20Foundation-FFFF00.svg)](https://unitary.foundation)
@@ -13,12 +13,17 @@ UCC interfaces automatically with multiple quantum computing frameworks, includi
 **Want to know more?** 
 - Check out our documentation, which you can build locally after installation by running `make html` in `ucc/docs/source`.
 - For code, repo, or theory questions, especially those requiring more detailed responses, submit a [Discussion](https://github.com/unitaryfund/ucc/discussions).
-- For casual or time sensitive questions, chat with us on [Discord](http://discord.unitary.fund).
+- For casual or time sensitive questions, chat with us on [Discord](http://discord.unitary.foundation).
 
 ## Quickstart
 
 ### Installation
 
+```bash
+pip install ucc
+```
+
+or install a dev version!
 ```bash
 git clone https://github.com/unitaryfund/ucc.git
 cd ucc
@@ -56,7 +61,7 @@ def test_cirq_compile():
         CNOT(qubits[0], qubits[1]))
     compile(circuit)
 ```
-
+<!-- start-how-does-ucc-stack-up -->
 ## How does UCC stack up?
 
 We run benchmarks regularly to compare against the most recent versions of the most popular quantum compiler frameworks for a range of circuits. Here's the latest:
@@ -65,10 +70,12 @@ And here you can see progress over time (changes usually indicate a newer versio
 ![alt text](benchmarks/avg_compiler_benchmarks_over_time.png)
 Note that the compile times before 2024-12-10 may have been run on different classical compute instances, so their exact runtime is not as important to compare as their relative performance with respect to other compilers.
 After 2024-12-10, all data present in this plot should be run on the same compute instance using our [ucc-benchmarks](https://github.com/unitaryfund/ucc/blob/main/.github/workflows/ucc-benchmarks.yml) GitHub Actions workflow. 
+<!-- end-how-does-ucc-stack-up -->
 
 ## Benchmarking
 
-You can benchmark the performance of ucc against other compilers using `scripts/run_benchmarks.sh`. This script runs compiler benchmarks in parallel, so you will need to first install `parallel` to support it. 
+You can benchmark the performance of ucc against other compilers using `./ucc/benchmarks/scripts/run_benchmarks.sh`. This script runs compiler benchmarks in parallel, so you will need to first install `parallel` to support it.    
+
 On Mac you can do this with `brew install parallel`. 
 
 ## Contributing
@@ -77,9 +84,9 @@ We’re building UCC as a community-driven project.
 Your contributions help improve the tool for everyone!
 There are many ways you can contribute, such as
 
-- **Create a Custom Compiler Pass**: Learn how in the [User Guide](./docs/source/user_guide.rst)
+- **Create a Custom Compiler Pass**: Learn how in the [User Guide](https://ucc.readthedocs.io/en/latest/user_guide.html)
 - **Submit a bug report or feature request**: Submit a bug report or feature request [on GitHub](https://github.com/unitaryfund/ucc/issues/new/choose).
-- **Contribute Code**: Follow the [Contribution Guide](./docs/source/contributing.rst) to submit new passes and improvements.
+- **Contribute Code**: Follow the [Contribution Guide](https://ucc.readthedocs.io/en/latest/contributing.html) to submit new passes and improvements.
 
 If you have questions about contributing please ask on the [Unitary Foundation Discord](http://discord.unitary.foundation).
 

docs/source/api.rst

@@ -6,7 +6,7 @@ This page details the publicly accessible functions available in ``ucc``.
 .. automodule:: ucc
     :members: compile
 
-.. autoclass:: ucc.transpilers.UCCTranspiler
+.. autoclass:: ucc.transpilers.ucc_defaults.UCCDefault1
     :members:
 
 .. automodule:: ucc.transpiler_passes

docs/source/conf.py

@@ -16,11 +16,20 @@
 # -- General configuration ---------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
 
-extensions = ["sphinx.ext.napoleon", "sphinx.ext.autodoc"]
+extensions = ["sphinx.ext.napoleon", "sphinx.ext.autodoc", "myst_parser"]
+# Suppress warnings related to heading levels
+suppress_warnings = [
+    'myst.header'
+]
+
+# Optionally, enable cross-referencing for `.rst` files as well
+myst_crossref = True
 
 templates_path = ["_templates"]
 exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
 
+source_suffix = [".rst", ".md"]  # Allow Sphinx to process both .rst and .md files
+
 
 # -- Options for HTML output -------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output

docs/source/index.rst

@@ -1,22 +1,20 @@
-Welcome to ucc's documentation!
+Welcome to the docs!
 ===============================
 
-Getting started
----------------
-
-To install ``ucc`` run ::
-
-    git clone https://github.com/unitaryfund/ucc.git
-    cd ucc
-    pip install -e . # Editable mode
+.. include:: ../../README.md
+   :parser: myst_parser.sphinx_
+   :end-before: <!-- start-how-does-ucc-stack-up -->
 
+.. include:: ../../README.md
+   :parser: myst_parser.sphinx_
+   :start-after: <!-- end-how-does-ucc-stack-up -->
 
 .. toctree::
-   :maxdepth: 2
+   :maxdepth: 1
    :caption: Contents:
 
-   API-doc <api.rst>
    User Guide <user_guide.rst>
+   API-doc <api.rst>
    Contributing Guide <contributing.rst>
    Developer Documentation <dev.rst>
    Code of Conduct <CODE_OF_CONDUCT.rst>

requirements.txt

@@ -7,3 +7,4 @@ ply>=3.11
 pytest>=6.0
 pytest-cov>=2.10
 sphinx>=8.1.3
+myst-parser>=0.15