From a77f979bd3c5b30afd12912797fc564c9aa68f59 Mon Sep 17 00:00:00 2001 From: Kartik Singhal Date: Fri, 6 Oct 2023 14:13:14 -0600 Subject: [PATCH] Add docs generation capability --- Makefile | 8 +++++-- docs/Makefile | 20 +++++++++++++++++ docs/conf.py | 1 - docs/index.rst | 41 ----------------------------------- docs/source/conf.py | 38 ++++++++++++++++++++++++++++++++ docs/source/index.rst | 19 ++++++++++++++++ docs/source/modules.rst | 7 ++++++ docs/source/phir.rst | 21 ++++++++++++++++++ docs/source/phir.sharding.rst | 21 ++++++++++++++++++ pyproject.toml | 2 ++ 10 files changed, 134 insertions(+), 44 deletions(-) create mode 100644 docs/Makefile delete mode 100644 docs/conf.py delete mode 100644 docs/index.rst create mode 100644 docs/source/conf.py create mode 100644 docs/source/index.rst create mode 100644 docs/source/modules.rst create mode 100644 docs/source/phir.rst create mode 100644 docs/source/phir.sharding.rst diff --git a/Makefile b/Makefile index a65bf3e..e166518 100644 --- a/Makefile +++ b/Makefile @@ -1,4 +1,4 @@ -.PHONY: tests lint clean build install dev +.PHONY: tests lint clean build install dev docs tests: pytest -s -x -vv tests/test*.py @@ -7,7 +7,7 @@ lint: pre-commit run --all-files clean: - rm -rf *.egg-info dist build + rm -rf *.egg-info dist build docs/build build: clean python -m build --sdist -n @@ -17,3 +17,7 @@ install: dev: pip install -e . + +docs: + # sphinx-apidoc -f -o docs/source/ pytket + sphinx-build -M html docs/source/ docs/build/ diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 0000000..d0c3cbf --- /dev/null +++ b/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) diff --git a/docs/conf.py b/docs/conf.py deleted file mode 100644 index f9d637a..0000000 --- a/docs/conf.py +++ /dev/null @@ -1 +0,0 @@ -"""Docs configuration file.""" diff --git a/docs/index.rst b/docs/index.rst deleted file mode 100644 index 3d73a6f..0000000 --- a/docs/index.rst +++ /dev/null @@ -1,41 +0,0 @@ -pytket-phir -====== - -.. toctree:: - :maxdepth: 2 - :caption: Contents: - - installation - usage - utils - -Installation ------------- - -To install pytket-phir, simply run: - -.. code-block:: bash - - pip install pytket-phir - -Usage ------ - -To use pytket-phir, import the main module: - -.. code-block:: python - - from pytket.phir import main - - main.run() - -Utils ------ - -The utils module contains various utility functions that can be used in conjunction with pytket-phir. To use the utils module, import it like so: - -.. code-block:: python - - from pytket.phir import utils - - utils.do_something() diff --git a/docs/source/conf.py b/docs/source/conf.py new file mode 100644 index 0000000..84bd352 --- /dev/null +++ b/docs/source/conf.py @@ -0,0 +1,38 @@ +# Configuration file for the Sphinx documentation builder. +# +# For the full list of built-in configuration values, see the documentation: +# https://www.sphinx-doc.org/en/master/usage/configuration.html + +# If extensions (or modules to document with autodoc) are in another directory, +# add these directories to sys.path here. +import pathlib +import sys + +sys.path.insert(0, pathlib.Path("../../pytket").resolve().as_posix()) +# print(sys.path) + +# -- Project information ----------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information + +project = "pytket.phir" +project_copyright = "2023, Quantinuum" +author = "Quantinuum" +release = "0.0.1" + +# -- General configuration --------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration + +extensions = [ + "sphinx.ext.doctest", + "sphinx.ext.autodoc", + "sphinx.ext.autosummary", + "sphinx.ext.napoleon", +] + +exclude_patterns = [] + + +# -- Options for HTML output ------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output + +html_theme = "sphinx_rtd_theme" diff --git a/docs/source/index.rst b/docs/source/index.rst new file mode 100644 index 0000000..d24898c --- /dev/null +++ b/docs/source/index.rst @@ -0,0 +1,19 @@ +pytket-phir +=========== + +.. toctree:: + :maxdepth: 2 + :caption: Contents: + + modules + +PHIR stands for `PECOS `__ +*High-level Intermediate Representation*. See `PHIR +specification `__ +for more. + +Indices and tables +================== + +* :ref:`genindex` +* :ref:`modindex` diff --git a/docs/source/modules.rst b/docs/source/modules.rst new file mode 100644 index 0000000..e1f1009 --- /dev/null +++ b/docs/source/modules.rst @@ -0,0 +1,7 @@ +pytket +====== + +.. toctree:: + :maxdepth: 4 + + phir diff --git a/docs/source/phir.rst b/docs/source/phir.rst new file mode 100644 index 0000000..197cefd --- /dev/null +++ b/docs/source/phir.rst @@ -0,0 +1,21 @@ +phir package +============ + +Subpackages +----------- + +.. toctree:: + :maxdepth: 4 + + phir.sharding + +Submodules +---------- + +phir.main module +---------------- + +.. automodule:: phir.main + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/source/phir.sharding.rst b/docs/source/phir.sharding.rst new file mode 100644 index 0000000..9b65767 --- /dev/null +++ b/docs/source/phir.sharding.rst @@ -0,0 +1,21 @@ +phir.sharding package +===================== + +Submodules +---------- + +phir.sharding.shard module +-------------------------- + +.. automodule:: phir.sharding.shard + :members: + :undoc-members: + :show-inheritance: + +phir.sharding.sharder module +---------------------------- + +.. automodule:: phir.sharding.sharder + :members: + :undoc-members: + :show-inheritance: diff --git a/pyproject.toml b/pyproject.toml index ca5665b..d366f70 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -17,6 +17,8 @@ dependencies = ["pytket"] [project.optional-dependencies] tests = ["pytest"] +docs = ["sphinx", "sphinx-rtd-theme"] + [project.urls] Repository = "https://github.com/CQCL/pytket-phir.git"