Merge pull request #50 from mmcdermott/add_mkdocs

Add mkdocs and readthedocs

.github/workflows/tests.yaml

@@ -34,7 +34,7 @@ jobs:
       #----------------------------------------------
       - name: Run tests
         run: |
-          pytest -v --doctest-modules --cov=src --junitxml=junit.xml -s --ignore=benchmark --ignore=sample_dataset_builder
+          pytest -v --doctest-modules --cov=src --junitxml=junit.xml -s --ignore=benchmark --ignore=sample_dataset_builder --ignore=docs
 
       - name: Upload coverage to Codecov
         uses: codecov/[email protected]

.mkdocs.yml

@@ -0,0 +1,45 @@
+site_name: MEDS-Transforms
+repo_url: https://github.com/mmcdermott/MEDS_transforms
+site_description: Documentation for the MEDS Transforms package
+site_author: Matthew McDermott
+
+nav:
+  - Home: index.md
+  - "Pipeline Configuration": pipeline_configuration.md
+  - "Pre-processing Operations": preprocessing_operation_prototypes.md
+  - "Terminology": terminology.md
+  - API: api/
+  - Issues: https://github.com/mmcdermott/MEDS_transforms/issues
+
+theme:
+  name: material
+  locale: en
+
+markdown_extensions:
+  - smarty
+  - pymdownx.arithmatex:
+      generic: true
+  - pymdownx.highlight:
+      anchor_linenums: true
+  - pymdownx.inlinehilite
+  - pymdownx.smartsymbols
+  - pymdownx.snippets
+  - pymdownx.tabbed:
+      alternate_style: true
+  - pymdownx.superfences
+
+extra_javascript:
+  - javascripts/mathjax.js
+  - https://unpkg.com/mathjax@3/es5/tex-mml-chtml.js
+
+plugins:
+  - search
+  - gen-files:
+      scripts:
+        - docs/gen_ref_pages.py
+  - literate-nav:
+      nav_file: SUMMARY.md
+  - section-index
+  - mkdocstrings
+  - git-authors
+  - git-revision-date-localized

.pre-commit-config.yaml

@@ -1,7 +1,7 @@
 default_language_version:
   python: python3
 
-exclude: "sample_dataset/dataset.pkl"
+exclude: "sample_dataset/dataset.pkl|docs/index.md"
 
 repos:
   - repo: https://github.com/pre-commit/pre-commit-hooks
@@ -95,10 +95,12 @@ repos:
           - mdformat-gfm
           - mdformat-tables
           - mdformat_frontmatter
-          - mdformat-myst
           - mdformat-black
           - mdformat-config
           - mdformat-shfmt
+          - mdformat-mkdocs
+          - mdformat-toc
+          - mdformat-admon
 
   # word spelling linter
   - repo: https://github.com/codespell-project/codespell

.readthedocs.yaml

@@ -0,0 +1,21 @@
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+
+# Set the version of Python and other tools you might need
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.12"
+
+python:
+  install:
+    - method: pip
+      path: .
+      extra_requirements:
+        - docs
+
+mkdocs:
+  configuration: .mkdocs.yml

docs/gen_ref_pages.py

@@ -0,0 +1,35 @@
+"""Generate the code reference pages."""
+
+from pathlib import Path
+
+import mkdocs_gen_files
+
+nav = mkdocs_gen_files.Nav()
+
+root = Path(__file__).parent.parent
+src = root / "src"
+
+for path in sorted(src.rglob("*.py")):
+    module_path = path.relative_to(src).with_suffix("")
+    doc_path = path.relative_to(src).with_suffix(".md")
+    full_doc_path = "api" / doc_path
+
+    parts = tuple(module_path.parts)
+
+    if parts[-1] == "__init__":
+        parts = parts[:-1]
+        doc_path = doc_path.with_name("index.md")
+        full_doc_path = full_doc_path.with_name("index.md")
+    elif parts[-1] == "__main__":
+        continue
+
+    nav[parts] = doc_path.as_posix()
+
+    with mkdocs_gen_files.open(full_doc_path, "w") as fd:
+        ident = ".".join(parts)
+        fd.write(f"::: {ident}")
+
+    mkdocs_gen_files.set_edit_path(full_doc_path, path.relative_to(root))
+
+with mkdocs_gen_files.open("api/SUMMARY.md", "w") as nav_file:
+    nav_file.writelines(nav.build_literate_nav())

docs/index.md

@@ -0,0 +1 @@
+--8<-- "README.md"

docs/javascripts/mathjax.js

@@ -0,0 +1,19 @@
+window.MathJax = {
+  tex: {
+    inlineMath: [["\\(", "\\)"]],
+    displayMath: [["\\[", "\\]"]],
+    processEscapes: true,
+    processEnvironments: true
+  },
+  options: {
+    ignoreHtmlClass: ".*|",
+    processHtmlClass: "arithmatex"
+  }
+};
+
+document$.subscribe(() => {
+  MathJax.startup.output.clearCache()
+  MathJax.typesetClear()
+  MathJax.texReset()
+  MathJax.typesetPromise()
+})

pyproject.toml

@@ -24,6 +24,11 @@ dependencies = ["safetensors", "numpy"]
 dev = ["pre-commit<4"]
 tests = ["pytest", "pytest-cov"]
 benchmarks = ["ml-mixins", "torch", "rootutils", "memray"]
+docs = [
+  "mkdocs==1.6.0", "mkdocs-material==9.5.31", "mkdocstrings[python,shell]==0.25.2", "mkdocs-gen-files==0.5.0",
+  "mkdocs-literate-nav==0.6.1", "mkdocs-section-index==0.3.9", "mkdocs-git-authors-plugin==0.9.0",
+  "mkdocs-git-revision-date-localized-plugin==1.2.6"
+]
 
 [project.urls]
 Homepage = "https://github.com/mmcdermott/nested_ragged_tensors"

src/nested_ragged_tensors/ragged_numpy.py

@@ -679,6 +679,7 @@ def __getitem__(self, idx: int | slice | np.ndarray):
 
         If we drop all values from a tensor, it is omitted from the resulting tensor. This is likely not
         ideal. TODO(mmd): Fix this behavior.
+
             >>> as_dense = J[2][0:1].to_dense()
             >>> assert as_dense.keys() == {'T', 'dim1/mask'}
             >>> as_dense['T']