diff --git a/.github/workflows/tests.yaml b/.github/workflows/tests.yaml index 2ac906a..9d415c9 100644 --- a/.github/workflows/tests.yaml +++ b/.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/codecov-action@v4.0.1 diff --git a/.mkdocs.yml b/.mkdocs.yml new file mode 100644 index 0000000..33de7a6 --- /dev/null +++ b/.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 diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index f29c310..a3f5e1e 100644 --- a/.pre-commit-config.yaml +++ b/.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 diff --git a/.readthedocs.yaml b/.readthedocs.yaml new file mode 100644 index 0000000..b0c0d54 --- /dev/null +++ b/.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 diff --git a/docs/gen_ref_pages.py b/docs/gen_ref_pages.py new file mode 100644 index 0000000..d38acd7 --- /dev/null +++ b/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()) diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 0000000..612c7a5 --- /dev/null +++ b/docs/index.md @@ -0,0 +1 @@ +--8<-- "README.md" diff --git a/docs/javascripts/mathjax.js b/docs/javascripts/mathjax.js new file mode 100644 index 0000000..7e48906 --- /dev/null +++ b/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() +}) diff --git a/pyproject.toml b/pyproject.toml index cd0bd74..85559b7 100644 --- a/pyproject.toml +++ b/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" diff --git a/src/nested_ragged_tensors/ragged_numpy.py b/src/nested_ragged_tensors/ragged_numpy.py index 5914eb4..d87055c 100644 --- a/src/nested_ragged_tensors/ragged_numpy.py +++ b/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']