WIP: sync latest Qick changes

.gitignore

@@ -37,8 +37,8 @@ build/
 dist/
 
 # Sphinx documentation
-docs/_build/
-docs/_autosummary/
+*_build/
+*_autosummary/
 
 ### macOS template
 # General
@@ -71,3 +71,8 @@ Temporary Items
 
 !/.gitignore
 !/README.md
+
+.vscode/
+*.tmp
+*.cache/
+*.hw/

.gitmodules

@@ -0,0 +1,18 @@
+[submodule "firmware/Hog"]
+	path = firmware/Hog
+	url = https://gitlab.com/hog-cern/Hog.git
+[submodule "firmware/QCE2024"]
+	path = firmware/QCE2024
+	url = git@github.com:openquantumhardware/QCE2024.git
+[submodule "firmware/qick_fw_misc"]
+	path = firmware/qick_fw_misc
+	url = git@github.com:openquantumhardware/qick_fw_misc.git
+[submodule "firmware/qick_tools"]
+	path = firmware/qick_tools
+	url = git@github.com:openquantumhardware/qick-tools.git
+[submodule "firmware/qick_fw_other"]
+	path = firmware/qick_fw_other
+	url = git@github.com:openquantumhardware/qick_fw_other.git
+[submodule "firmware/qick_fw_mkids"]
+	path = firmware/qick_fw_mkids
+	url = git@github.com:openquantumhardware/qick_fw_mkids.git

docs/Makefile

@@ -15,9 +15,9 @@ endif
 # Internal variables.
 PAPEROPT_a4     = -D latex_paper_size=a4
 PAPEROPT_letter = -D latex_paper_size=letter
-ALLSPHINXOPTS   = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
+ALLSPHINXOPTS   = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source
 # the i18n builder cannot share the environment and doctrees with the others
-I18NSPHINXOPTS  = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
+I18NSPHINXOPTS  = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source
 
 .PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest coverage gettext
 
@@ -85,11 +85,11 @@ htmlhelp:
 qthelp:
 	$(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp
 	@echo
-	@echo "Build finished; now you can run "qcollectiongenerator" with the" \
+	@echo "Build finished; now you can run \"qcollectiongenerator\" with the" \
 	      ".qhcp project file in $(BUILDDIR)/qthelp, like this:"
-	@echo "# qcollectiongenerator $(BUILDDIR)/qthelp/SphinxApidocTurorial.qhcp"
+	@echo "# qcollectiongenerator $(BUILDDIR)/qthelp/project_name.qhcp"
 	@echo "To view the help file:"
-	@echo "# assistant -collectionFile $(BUILDDIR)/qthelp/SphinxApidocTurorial.qhc"
+	@echo "# assistant -collectionFile $(BUILDDIR)/qthelp/project_name.qhc"
 
 applehelp:
 	$(SPHINXBUILD) -b applehelp $(ALLSPHINXOPTS) $(BUILDDIR)/applehelp
@@ -104,8 +104,8 @@ devhelp:
 	@echo
 	@echo "Build finished."
 	@echo "To view the help file:"
-	@echo "# mkdir -p $$HOME/.local/share/devhelp/SphinxApidocTurorial"
-	@echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/SphinxApidocTurorial"
+	@echo "# mkdir -p $$HOME/.local/share/devhelp/project_name"
+	@echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/project_name"
 	@echo "# devhelp"
 
 epub:
@@ -130,7 +130,7 @@ latexpdfja:
 	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
 	@echo "Running LaTeX files through platex and dvipdfmx..."
 	$(MAKE) -C $(BUILDDIR)/latex all-pdf-ja
-	@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
+	@echo "platex/dvipdfmx finished; the PDF files are in $(BUILDDIR)/latex."
 
 text:
 	$(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text

docs/requirements.txt

@@ -1,3 +1,8 @@
 numpy>=1.14.2
 tqdm
+sphinx
 sphinx-rtd-theme
+nbsphinx
+myst-parser
+ipython
+ipykernel

docs/source/_autosummary/qick.tprocv2_assembler.rst

@@ -0,0 +1,29 @@
+qick.tprocv2\_assembler
+=======================
+
+.. automodule:: qick.tprocv2_assembler
+
+
+   .. rubric:: Functions
+
+   .. autosummary::
+
+      check_lit
+      check_name
+      check_num
+      check_reg
+      find_pattern
+      get_imm_dt
+      get_reg_addr
+      get_src_type
+      integer2bin
+      parse_labels
+
+   .. rubric:: Classes
+
+   .. autosummary::
+
+      Assembler
+      Instruction
+      LFSR
+

docs/source/_static/custom.css

@@ -0,0 +1,21 @@
+body {
+  --themecolor: black;
+}
+
+.wy-side-nav-search {
+  background-color: var(--themecolor);
+}
+.wy-nav-top {
+  background-color: var(--themecolor);
+}
+
+/* override table width restrictions */
+.wy-table-responsive table td, .wy-table-responsive table th {
+    /* !important prevents the common CSS stylesheets from
+       overriding this as on RTD they are loaded after this stylesheet */
+    white-space: normal !important;
+}
+
+.wy-table-responsive {
+    overflow: visible !important;
+}

docs/source/conf.py

@@ -0,0 +1,196 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+#
+# QICK documentation build configuration file
+#
+# This file is execfile()d with the current directory set to its
+# containing dir.
+
+import sys
+import os
+import pathlib
+import shutil
+
+#Check if Pandoc is installed
+if shutil.which('pandoc') is None:
+    import warnings
+    warnings.warn(
+        "pandoc not found. Install it with: sudo apt install pandoc (Linux) "
+        "or brew install pandoc (macOS). Required for notebook conversion."
+    )
+
+# -- Path setup --------------------------------------------------------------
+
+# Make your modules available in sys.path
+here = pathlib.Path(__file__).parent.resolve()
+sys.path.insert(0, (here / '../../qick_lib').resolve().as_posix())
+print(f"Python path: {sys.path[0]}")
+
+def get_version(rel_path):
+    """
+    qick_lib/qick/VERSION is a text file containing only the version number.
+    """
+    return (here / rel_path).read_text().strip()
+
+# -- Project information -----------------------------------------------------
+
+project = 'QICK'
+copyright = 'OpenQuantumHardware'
+author = 'OpenQuantumHardware'
+
+# The short X.Y version.
+version = get_version("../../qick_lib/qick/VERSION")
+# The full version, including alpha/beta/rc tags.
+release = version
+
+# -- General configuration ---------------------------------------------------
+
+# Add any Sphinx extension module names here
+extensions = [
+    'sphinx.ext.autodoc',
+    'sphinx.ext.viewcode',
+    'sphinx.ext.intersphinx',
+    'sphinx.ext.mathjax',
+    'sphinx.ext.autosummary',
+    'sphinx.ext.napoleon',
+    'sphinx.ext.extlinks',
+    'nbsphinx',                      # For Jupyter notebooks
+    'myst_parser',                   # For Markdown files
+]
+
+# nbsphinx configuration
+nbsphinx_execute = 'never'           # Don't execute notebooks during build
+nbsphinx_allow_errors = True         # Continue even if notebooks have errors
+nbsphinx_timeout = 120               # Timeout for notebook execution (seconds)
+
+# autodoc configuration
+autodoc_member_order = 'bysource'
+autodoc_default_options = {
+    'members': True,
+    'show-inheritance': True,
+    'special-members': '__init__',
+    'undoc-members': True,
+    'exclude-members': '__weakref__'
+}
+
+# Mock imports for modules that are not available during documentation build
+autodoc_mock_imports = ["pynq", "xrfclk", "xrfdc", "cffi", "Pyro4", "psutil"]
+
+# Generate autodoc stubs with summaries from code
+autosummary_generate = True
+
+# Add any paths that contain templates here
+templates_path = ['_templates']
+
+# The suffix(es) of source filenames
+source_suffix = {
+    '.rst': 'restructuredtext',
+    '.md': 'markdown',
+    #'.ipynb': 'jupyter_notebooks',
+}
+
+# The master toctree document
+master_doc = 'index'
+
+# The language for content
+language = 'en'
+
+# List of patterns to ignore when looking for source files
+exclude_patterns = [
+    '_build',
+    'Thumbs.db',
+    '.DS_Store',
+    '**.ipynb_checkpoints',  # Exclude Jupyter checkpoint files
+]
+
+# The name of the Pygments (syntax highlighting) style
+pygments_style = 'sphinx'
+
+# -- Options for HTML output -------------------------------------------------
+
+# The theme to use for HTML pages
+html_theme = 'sphinx_rtd_theme'
+
+# Theme options
+html_theme_options = {
+    'logo_only': True,
+    'navigation_depth': 4,
+}
+
+# The name of an image file to place at the top of the sidebar
+html_logo = "../../graphics/logoQICK.svg"
+
+# Add any paths that contain custom static files
+html_static_path = ['_static']
+
+# Custom CSS files
+html_css_files = ['custom.css']
+
+# If true, links to the reST sources are added to the pages
+html_show_sourcelink = True
+
+# If true, "Created using Sphinx" is shown in the HTML footer
+html_show_sphinx = True
+
+# If true, "(C) Copyright ..." is shown in the HTML footer
+html_show_copyright = True
+
+# Output file base name for HTML help builder
+htmlhelp_basename = 'QICKdoc'
+
+# -- Options for LaTeX output ------------------------------------------------
+
+latex_elements = {
+    'papersize': 'letterpaper',
+    'pointsize': '10pt',
+    'figure_align': 'htbp',
+}
+
+# Grouping the document tree into LaTeX files
+latex_documents = [
+    (master_doc, 'QICK.tex', 'QICK Documentation',
+     author, 'manual'),
+]
+
+# -- Options for manual page output ------------------------------------------
+
+man_pages = [
+    (master_doc, 'qick', 'QICK Documentation',
+     [author], 1)
+]
+
+# -- Options for Texinfo output ----------------------------------------------
+
+texinfo_documents = [
+    (master_doc, 'QICK', 'QICK Documentation',
+     author, 'QICK', 'Quantum Instrumentation Control Kit',
+     'Miscellaneous'),
+]
+
+# -- Intersphinx configuration -----------------------------------------------
+
+intersphinx_mapping = {
+    'python': ('https://docs.python.org/3.10', None),
+    'numpy': ('https://numpy.org/doc/stable', None),
+    'pynq': ('https://pynq.readthedocs.io/en/latest', None),
+}
+
+# -- Extlinks configuration --------------------------------------------------
+
+extlinks = {
+    'repofile': ('https://github.com/openquantumhardware/qick/blob/main/%s', '%s'),
+}
+
+extlinks_detect_hardcoded_links = True
+
+# -- Linkcheck configuration ------------------------------------------------
+
+linkcheck_ignore = [
+    r'^https://blogs.keysight.com/',  # gives 403 error
+    r'^http://localhost',              # ignore local servers
+]
+
+# -- Custom CSS -------------------------------------------------------------
+
+def setup(app):
+    app.add_css_file("custom.css")

docs/source/contact.rst

@@ -0,0 +1,10 @@
+Support and community
+---------------------
+
+The main resource for communicating with developers and members of the QICK community is the Unitary Foundation Discord (use this `invite link <http://discord.unitary.foundation/>`_):
+
+* Chat with us any time in the `#qick channel <https://discord.com/channels/764231928676089909/1036774653479362630>`_.
+
+* If you prefer voice chat, we also hold weekly office hours; check the `Unitary Foundation calendar <https://unitary.foundation/community/events/>`_ for details.
+
+We also welcome bug reports and feature requests via `GitHub Issues <https://github.com/openquantumhardware/qick/issues>`_.