Reference Docs (#1684)

- Use `griffe` and some custom templating code to emit clean markdown
files for our reference docs
 - Go through docstrings, fix issues, add additional information

Author: mpharrigan

check/mypy-dev-tools

@@ -15,7 +15,7 @@ cd "${topdir}" || exit $?
 CONFIG_FILE='mypy.ini'
 
 echo -e -n "\033[31m"
-mypy --config-file=dev_tools/conf/$CONFIG_FILE "$@" dev_tools/
+mypy --config-file=dev_tools/conf/$CONFIG_FILE --no-namespace-packages "$@" dev_tools/
 result=$?
 echo -e -n "\033[0m"
 

dev_tools/build-reference-docs-2.py

@@ -0,0 +1,19 @@
+#  Copyright 2025 Google LLC
+#
+#  Licensed under the Apache License, Version 2.0 (the "License");
+#  you may not use this file except in compliance with the License.
+#  You may obtain a copy of the License at
+#
+#      https://www.apache.org/licenses/LICENSE-2.0
+#
+#  Unless required by applicable law or agreed to in writing, software
+#  distributed under the License is distributed on an "AS IS" BASIS,
+#  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+#  See the License for the specific language governing permissions and
+#  limitations under the License.
+
+from qualtran_dev_tools.git_tools import get_git_root
+from qualtran_dev_tools.make_reference_docs import make_reference_docs
+
+if __name__ == "__main__":
+    make_reference_docs(get_git_root())

dev_tools/conf/mypy.ini

@@ -16,7 +16,7 @@ ignore_missing_imports = true
 # 3rd-party libs for which we don't have stubs
 
 # Google
-[mypy-google.api_core.*,google.auth.*,google.colab.*,google.protobuf.text_format.*,google.cloud.*]
+[mypy-google.api_core.*,google.auth.*,google.colab.*,google.protobuf.text_format.*,google.cloud.*,google.*]
 follow_imports = silent
 ignore_missing_imports = true
 

dev_tools/execute-notebooks.py

@@ -20,13 +20,11 @@
 def parse_args():
     p = argparse.ArgumentParser()
     p.add_argument('--output-nbs', action=argparse.BooleanOptionalAction, default=True)
-    p.add_argument('--output-html', action=argparse.BooleanOptionalAction, default=False)
+    p.add_argument('--output-md', action=argparse.BooleanOptionalAction, default=False)
     p.add_argument('--only-out-of-date', action=argparse.BooleanOptionalAction, default=True)
     args = p.parse_args()
     execute_and_export_notebooks(
-        output_nbs=args.output_nbs,
-        output_html=args.output_html,
-        only_out_of_date=args.only_out_of_date,
+        output_nbs=args.output_nbs, output_md=args.output_md, only_out_of_date=args.only_out_of_date
     )
 
 

dev_tools/qualtran_dev_tools/jupyter_autogen.py

@@ -16,7 +16,6 @@
 
 import abc
 import inspect
-import io
 import re
 import textwrap
 from pathlib import Path
@@ -29,6 +28,7 @@
 from qualtran import BloqDocSpec, BloqExample
 
 from .parse_docstrings import get_markdown_docstring_lines
+from .write_if_different import WriteIfDifferent
 
 _IMPORTS = """\
 from qualtran import Bloq, CompositeBloq, BloqBuilder, Signature, Register
@@ -310,84 +310,6 @@ def _init_notebook(
     return nb, nb_path
 
 
-class WriteIfDifferent:
-    """A file-like object that only writes to disk if the new content
-    differs from the existing content.
-
-    Args:
-        path: The path to write, which may already exist.
-    """
-
-    def __init__(self, path: Path):
-        self.path = path
-        self._buffer = io.StringIO()
-
-    def write(self, s: str):
-        return self._buffer.write(s)
-
-    def writelines(self, lines):
-        for line in lines:
-            self.write(line)
-
-    def flush(self):
-        self._buffer.flush()
-
-    def close(self):
-        """Closes the adapter.
-
-        This triggers the comparison of buffered content
-        with the disk file's content and writes to disk only if different.
-        """
-        new_content = self._buffer.getvalue()
-        self._buffer.close()
-
-        existing_content = None
-        if self.path.is_file():
-            with self.path.open('r') as f_read:
-                existing_content = f_read.read()
-            if new_content == existing_content:
-                print(f"{self.path} unchanged.")
-                return
-
-        with self.path.open('w') as f_write:
-            f_write.write(new_content)
-
-    def __enter__(self):
-        return self
-
-    def __exit__(self, exc_type, exc_val, exc_tb):
-        self.close()
-        # Do not suppress exceptions from the 'with' block body.
-        return False
-
-    @property
-    def closed(self):
-        return self._buffer.closed
-
-    def readable(self):
-        """Returns False, as this adapter is write-only like a file from `open('w')`."""
-        return False
-
-    def writable(self):
-        """Returns True if the adapter is not closed, False otherwise."""
-        return self._buffer.writable()
-
-    def seekable(self):
-        """Returns False, as this adapter is not seekable like a disk file opened in 'w' mode."""
-        return False
-
-    def tell(self):
-        """Returns the current stream position in the internal buffer."""
-        return self._buffer.tell()
-
-    def truncate(self, size=None):
-        """
-        Resizes the internal buffer to the given number of bytes.
-        If size is not specified, resizes to the current position.
-        """
-        return self._buffer.truncate(size)
-
-
 def render_notebook(nbspec: NotebookSpecV2) -> None:
     # 1. get a notebook (existing or empty)
     nb, nb_path = _init_notebook(path_stem=nbspec.path_stem, directory=nbspec.directory)

dev_tools/qualtran_dev_tools/make_reference_docs/__init__.py

@@ -0,0 +1,15 @@
+#  Copyright 2024 Google LLC
+#
+#  Licensed under the Apache License, Version 2.0 (the "License");
+#  you may not use this file except in compliance with the License.
+#  You may obtain a copy of the License at
+#
+#      https://www.apache.org/licenses/LICENSE-2.0
+#
+#  Unless required by applicable law or agreed to in writing, software
+#  distributed under the License is distributed on an "AS IS" BASIS,
+#  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+#  See the License for the specific language governing permissions and
+#  limitations under the License.
+
+from ._make import make_reference_docs

dev_tools/qualtran_dev_tools/make_reference_docs/_components/__init__.py

@@ -0,0 +1,13 @@
+#  Copyright 2024 Google LLC
+#
+#  Licensed under the Apache License, Version 2.0 (the "License");
+#  you may not use this file except in compliance with the License.
+#  You may obtain a copy of the License at
+#
+#      https://www.apache.org/licenses/LICENSE-2.0
+#
+#  Unless required by applicable law or agreed to in writing, software
+#  distributed under the License is distributed on an "AS IS" BASIS,
+#  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+#  See the License for the specific language governing permissions and
+#  limitations under the License.

dev_tools/qualtran_dev_tools/make_reference_docs/_components/aliases.py

@@ -0,0 +1,30 @@
+#  Copyright 2024 Google LLC
+#
+#  Licensed under the Apache License, Version 2.0 (the "License");
+#  you may not use this file except in compliance with the License.
+#  You may obtain a copy of the License at
+#
+#      https://www.apache.org/licenses/LICENSE-2.0
+#
+#  Unless required by applicable law or agreed to in writing, software
+#  distributed under the License is distributed on an "AS IS" BASIS,
+#  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+#  See the License for the specific language governing permissions and
+#  limitations under the License.
+from typing import Dict
+
+
+def get_aliases_str(pref_dotpath: str, *, aliases_d: Dict[str, str]) -> str:
+    """From a complete dictionary of aliases, return a formatted string with our aliases.
+
+    This will return just `pref_dotpath` if there are none,
+    otherwise '{pref} **Alias(es):** {...}'
+    """
+    aliases = [k for k, v in aliases_d.items() if v == pref_dotpath and k != pref_dotpath]
+    s = f'`{pref_dotpath}`'
+    alias_str = ', '.join(f'`{a}`' for a in aliases)
+    if len(aliases) > 1:
+        s += f". **Aliases:** {alias_str}"
+    elif len(aliases) == 1:
+        s += f". **Alias:** {alias_str}"
+    return s