📝 Initialize Documentation on ReadTheDocs

.readthedocs.yaml

@@ -0,0 +1,23 @@
+version: 2
+
+submodules:
+  include: all
+  recursive: true
+
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.9"
+  apt_packages:
+    - cmake
+    - libboost-all-dev
+
+sphinx:
+  configuration: docs/source/conf.py
+
+python:
+  install:
+    - method: pip
+      path: .
+      extra_requirements:
+        - docs

docs/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = source
+BUILDDIR      = build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/make.bat

@@ -0,0 +1,35 @@
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=source
+set BUILDDIR=build
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+	echo.
+	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+	echo.installed, then set the SPHINXBUILD environment variable to point
+	echo.to the full path of the 'sphinx-build' executable. Alternatively you
+	echo.may add the Sphinx directory to PATH.
+	echo.
+	echo.If you don't have Sphinx installed, grab it from
+	echo.https://www.sphinx-doc.org/
+	exit /b 1
+)
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+
+:end
+popd

docs/source/conf.py

@@ -0,0 +1,68 @@
+try:
+    from importlib import metadata
+except ImportError:
+    import importlib_metadata as metadata
+
+import pybtex.plugin
+from pybtex.style.formatting.unsrt import Style as UnsrtStyle
+from pybtex.style.template import field, href
+
+# -- Project information -----------------------------------------------------
+project = "SyReC"
+author = "Smaran Adarsh"
+
+release = metadata.version("mqt.syrec")
+version = ".".join(release.split(".")[:3])
+
+# -- General configuration ---------------------------------------------------
+extensions = [
+    "sphinx.ext.autodoc",
+    "sphinx.ext.autosectionlabel",
+    "sphinx.ext.intersphinx",
+    "sphinx.ext.autosummary",
+    "sphinx.ext.mathjax",
+    "sphinx.ext.napoleon",
+    "sphinx.ext.viewcode",
+    "sphinx.ext.githubpages",
+    "sphinxcontrib.bibtex",
+    "sphinx_copybutton",
+    "hoverxref.extension",
+]
+
+autosectionlabel_prefix_document = True
+
+hoverxref_auto_ref = True
+hoverxref_domains = ["cite", "py"]
+hoverxref_roles = []
+hoverxref_mathjax = True
+hoverxref_role_types = {
+    "ref": "tooltip",
+    "p": "tooltip",
+    "labelpar": "tooltip",
+    "class": "tooltip",
+    "meth": "tooltip",
+    "func": "tooltip",
+    "attr": "tooltip",
+    "property": "tooltip",
+}
+
+
+class CDAStyle(UnsrtStyle):
+    def format_url(self, e):
+        url = field("url", raw=True)
+        return href()[url, "[PDF]"]
+
+
+pybtex.plugin.register_plugin("pybtex.style.formatting", "cda_style", CDAStyle)
+
+bibtex_bibfiles = ["refs.bib"]
+bibtex_default_style = "cda_style"
+
+copybutton_prompt_text = r"(?:\(venv\) )?\$ "
+copybutton_prompt_is_regexp = True
+copybutton_line_continuation_character = "\\"
+
+autosummary_generate = True
+
+# -- Options for HTML output -------------------------------------------------
+html_theme = "sphinx_rtd_theme"

docs/source/index.rst

@@ -0,0 +1,4 @@
+Welcome to SyReC's documentation!
+=================================
+
+At the moment, this documentation is just blank. Expect this to change in the near future.

docs/source/refs.bib

@@ -0,0 +1,7 @@
+@inproceedings{wille2019towardsHDLsynthesis,
+    author = {Wille, Robert and Haghparast, Majid and Adarsh, Smaran and M, Tanmay},
+    title = {Towards {HDL}-based Synthesis of Reversible Circuits with No Additional Lines},
+    booktitle = {International Conference on Computer Aided Design},
+    year = {2019},
+    url = {https://www.cda.cit.tum.de/files/eda/2019_iccad_hdl_based_reversible_circuit_synthesis_without_additional_lines.pdf},
+}

noxfile.py

@@ -27,3 +27,18 @@ def pylint(session: Session) -> None:
     session.install("pylint")
     session.install("-e", ".")
     session.run("pylint", "mqt.syrec", "--extension-pkg-allow-list=mqt.syrec.pysyrec,PyQt6", *session.posargs)
+
+
+@nox.session
+def docs(session: Session) -> None:
+    """Build the documentation. Simply execute `nox -rs docs -- serve` to locally build and serve the docs."""
+    session.install(".[docs]")
+    session.chdir("docs")
+    session.run("sphinx-build", "-M", "html", "source", "_build")
+
+    if session.posargs:
+        if "serve" in session.posargs:
+            print("Launching docs at http://localhost:8000/ - use Ctrl-C to quit")
+            session.run("python", "-m", "http.server", "8000", "-d", "_build/html")
+        else:
+            print("Unsupported argument to docs")

setup.py

@@ -110,7 +110,16 @@ def build_extension(self, ext):
     extras_require={
         "test": ["pytest>=7"],
         "coverage": ["coverage[toml]~=6.4.2", "pytest-cov~=3.0.0"],
-        "dev": ["mqt.syrec[test, coverage]"],
+        "docs": [
+            "sphinx>=5.1.1",
+            "sphinx-rtd-theme",
+            "sphinxcontrib-bibtex~=2.5",
+            "sphinx-copybutton",
+            "sphinx-hoverxref~=1.1.3",
+            "pybtex>=0.24",
+            "importlib_metadata>=3.6; python_version < '3.10'",
+        ],
+        "dev": ["mqt.syrec[test, coverage, docs]"],
     },
     classifiers=[
         "Development Status :: 3 - Alpha",
@@ -132,7 +141,7 @@ def build_extension(self, ext):
     project_urls={
         "Source": "https://github.com/cda-tum/syrec/",
         "Tracker": "https://github.com/cda-tum/syrec/issues",
-        # 'Research': ''
+        "Documentation": "https://syrec.readthedocs.io",
     },
     install_requires=[
         "PyQt6>=6.2.3,<6.4.0",