.

deps/requirements.in

@@ -8,3 +8,4 @@ pyarrow>=17.0.0
 mysqlclient>=2.2.0
 connectorx>=0.3.0
 rdkit>=2024.3.1
+tqdm>=4.62.0

deps/requirements_docs.in

@@ -0,0 +1,10 @@
+mkdocs
+mkdocs-autorefs
+mkdocs-coverage
+mkdocs-gen-files
+mkdocs-literate-nav
+mkdocs-material[imaging]
+mkdocs-material-extensions
+mkdocstrings
+mkdocstrings-python
+mike

docs/index.md

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

mkdocs.yml

@@ -0,0 +1,101 @@
+site_name: bio-data-to-db
+site_url: 'https://deargen.github.io/bio-data-to-db'
+repo_url: 'https://github.com/deargen/bio-data-to-db'
+copyright: |
+  &copy; 2024 <a href="https://deargen.me"  target="_blank" rel="noopener">Deargen Inc.</a>
+watch: [mkdocs.yml, README.md, src/]
+validation:
+  omitted_files: warn
+  absolute_links: warn
+  unrecognized_links: warn
+
+nav:
+  - Home:
+      - Overview: index.md
+      - Changelog: CHANGELOG.md
+  # defer to gen-files + literate-nav
+  - API reference:
+      - mkdocstrings-python: reference/
+
+theme:
+  name: material
+  font:
+    text: Noto Sans Korean
+    code: Jetbrains Mono
+  features:
+    - toc.follow
+    - navigation.top
+    - navigation.footer
+    - navigation.sections
+    - navigation.tabs
+    - navigation.tabs.sticky
+    - navigation.indexes
+    - navigation.path
+    - search.suggest
+    - search.highlight
+    - content.tabs.link
+    - content.code.annotation
+    - content.code.copy
+  language: ko
+  palette:
+    - media: '(prefers-color-scheme: light)'
+      scheme: default
+      primary: teal
+      accent: purple
+      toggle:
+        icon: material/weather-sunny
+        name: Switch to dark mode
+    - media: '(prefers-color-scheme: dark)'
+      scheme: slate
+      primary: black
+      accent: lime
+      toggle:
+        icon: material/weather-night
+        name: Switch to system preference
+
+plugins:
+  - search
+  - gen-files:
+      scripts:
+        - scripts/gen_ref_nav.py
+  - literate-nav:
+      nav_file: SUMMARY.md
+  - mkdocstrings:
+      handlers:
+        python:
+          options:
+            show_symbol_type_heading: true
+            show_symbol_type_toc: true
+          paths: [src] # search packages in the src folder
+
+extra:
+  social:
+    - icon: fontawesome/brands/github-alt
+      link: https://github.com/deargen/python-project-template-2024
+  version:
+    provider: mike
+
+markdown_extensions:
+  - pymdownx.superfences:
+      custom_fences:
+        - name: mermaid
+          class: mermaid
+          format: !!python/name:pymdownx.superfences.fence_code_format
+  - pymdownx.highlight:
+      anchor_linenums: true
+  - pymdownx.inlinehilite
+  - pymdownx.snippets
+  - admonition
+  - pymdownx.arithmatex:
+      generic: true
+  - footnotes
+  - pymdownx.details
+  - pymdownx.superfences
+  - pymdownx.mark
+  - attr_list
+  - pymdownx.emoji:
+      emoji_index: !!python/name:material.extensions.emoji.twemoji
+      emoji_generator: !!python/name:material.extensions.emoji.to_svg
+  - pymdownx.tilde # strikethrough with ~~ ~~
+  - toc:
+      permalink: true

scripts/gen_ref_nav.py

@@ -0,0 +1,50 @@
+"""Generate the code reference pages and navigation."""
+
+from pathlib import Path
+
+import mkdocs_gen_files
+
+IGNORE_MODULES_EXACT = {
+    "bio_data_to_db.__init__",
+}
+
+IGNORE_MODULES_STARTSWITH = {
+    "bio_data_to_db.cli.",
+}
+
+nav = mkdocs_gen_files.Nav()
+mod_symbol = '<code class="doc-symbol doc-symbol-nav doc-symbol-module"></code>'
+
+src = Path(__file__).parent.parent / "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 = Path("reference", doc_path)
+
+    parts = tuple(module_path.parts)
+    module_str = ".".join(parts)
+
+    if module_str in IGNORE_MODULES_EXACT or any(
+        module_str.startswith(prefix) for prefix in IGNORE_MODULES_STARTSWITH
+    ):
+        print(f"Skipping module: {module_str}")
+        continue
+    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].startswith("_"):
+        continue
+
+    nav_parts = [f"{mod_symbol} {part}" for part in parts]
+    nav[tuple(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)
+
+with mkdocs_gen_files.open("reference/SUMMARY.md", "w") as nav_file:
+    nav_file.writelines(nav.build_literate_nav())

src/bio_data_to_db/__init__.py

@@ -1,8 +1,6 @@
 # Allow star imports
 # ruff: noqa: F403 F405
 
-from __future__ import annotations
-
 from .bio_data_to_db import *
 
 __doc__ = bio_data_to_db.__doc__

src/bio_data_to_db/utils/polars.py

@@ -8,7 +8,7 @@ def w_pbar(pbar: tqdm.std.tqdm, func: Callable[..., Any]) -> Callable[..., Any]:
     """
     Apply progress bar when using `map_elements` in `polars`.
 
-    Example:
+    Examples:
         >>> with tqdm(total=len(df)) as pbar:  # doctest: +SKIP
         ...     df = df.with_columns(
         ...         pl.col("in_col")

src/bio_data_to_db/utils/smiles.py

@@ -8,7 +8,7 @@
 
 
 @cache
-def canonical_smiles_wo_salt(smiles):
+def canonical_smiles_wo_salt(smiles: str) -> str | None:
     """
     Get the canonical SMILES without salt from the input SMILES.
 
@@ -35,7 +35,7 @@ def polars_canonical_smiles_wo_salt(
     *,
     smiles_col: str = "smiles",
     out_col: str = "canonical_smiles_wo_salt",
-):
+) -> pl.DataFrame:
     """
     Apply canonical_smiles_wo_salt on the DataFrame with tqdm.
     """