Merge pull request #90 from daizutabi/79-setting-source-directory-in-nav

Setting source directory in nav

.github/workflows/ci.yml

@@ -31,7 +31,9 @@ jobs:
           python-version: ${{ matrix.python-version }}
       - name: Install Hatch
         run: pip install --upgrade hatch
-      - name: Run tests
+      - name: Check format
+        run: hatch fmt --check
+      - name: Run test
         run: hatch run test
       - name: Upload Codecov Results
         if: success()

mkdocs.yml

@@ -58,8 +58,8 @@ nav:
     - usage/object.md
     - usage/page.md
     - usage/config.md
-  - API: $api/mkapi.**
-  - Examples: $api/examples.**
+  - API: $api:src/mkapi.**
+  - Examples: $api:src/examples.**
   # - Schemdraw: $api/schemdraw.***
   # - Polars: $api/polars.***
   # - Altair: $api/altair.***

pyproject.toml

@@ -83,20 +83,22 @@ ignore = [
   "COM812",
   "D105",
   "D406",
-  "G004",
   "D407",
   "EM102",
   "ERA001",
   "FIX002",
   "FIX003",
+  "G004",
   "ISC001",
   "N812",
   "PGH003",
   "PLR2004",
+  "PT001",
   "RET504",
   "TD",
   "TRY003",
 ]
+exclude = ["google.py", 'numpy.py']
 
 [tool.ruff.extend-per-file-ignores]
 "tests/*.py" = ["ANN", "D", "S101", "INP001", "T201", "PLR2004", "PGH003"]

src/mkapi/pages.py

@@ -9,7 +9,7 @@
 import mkapi.renderers
 from mkapi.globals import resolve_with_attribute
 from mkapi.importlib import get_object, load_module
-from mkapi.objects import Module, is_empty, iter_objects_with_depth
+from mkapi.objects import is_empty, iter_objects_with_depth
 from mkapi.renderers import get_object_filter_for_source
 from mkapi.utils import is_module_cache_dirty, split_filters
 

src/mkapi/plugins.py

@@ -16,7 +16,6 @@
 
 from halo import Halo
 from mkdocs.config import Config, config_options
-from mkdocs.config.defaults import MkDocsConfig
 from mkdocs.plugins import BasePlugin, get_plugin_logger
 from mkdocs.structure.files import File, InclusionLevel, get_files
 from tqdm.std import tqdm
@@ -32,9 +31,11 @@
     from collections.abc import Callable
 
     from mkdocs.config.defaults import MkDocsConfig
-    from mkdocs.structure.files import File, Files
+    from mkdocs.structure.files import Files
     from mkdocs.structure.pages import Page as MkDocsPage
     from mkdocs.structure.toc import AnchorLink, TableOfContents
+    # from mkdocs.structure.nav import Navigation
+    # from mkdocs.utils.templates import TemplateContext
 
 logger = get_plugin_logger("MkAPI")
 
@@ -156,6 +157,18 @@ def _update_bar(self, uri: str) -> None:
         if self.bar.n == self.bar.total:
             self.bar.close()
 
+    # def on_page_context(
+    #     self,
+    #     context: TemplateContext,
+    #     *,
+    #     page: MkDocsPage,
+    #     config: MkDocsConfig,
+    #     nav: Navigation,
+    # ) -> TemplateContext | None:
+    #     if len(nav.items):
+    #         nav.items.pop()
+    #     return context
+
     def on_shutdown(self) -> None:
         for path in self.api_dirs:
             if path.exists():
@@ -199,31 +212,43 @@ def _watch_directory(name: str, config: MkDocsConfig) -> None:
             config.watch.append(path)
 
 
+def _mkdir(path: Path, paths: list[Path]) -> None:
+    if path.exists() and path not in paths:
+        logger.warning(f"API directory exists: {path}")
+        ans = input("Delete the directory? [yes/no] ")
+        if ans.lower() == "yes":
+            logger.info(f"Deleting API directory: {path}")
+            shutil.rmtree(path)
+        else:
+            logger.error("Delete the directory manually.")
+            sys.exit()
+    if not path.exists():
+        msg = f"Making API directory: {path}"
+        logger.info(msg)
+        path.mkdir(parents=True)
+        paths.append(path)
+
+
+def _split_path(path: str, plugin: MkAPIPlugin) -> list[str]:
+    if ":" in path:
+        return path.split(":", maxsplit=1)
+    return [path, plugin.config.src_dir]
+
+
 def _create_nav(config: MkDocsConfig, plugin: MkAPIPlugin) -> None:
     if not config.nav:
         return
 
     def mkdir(name: str, path: str) -> list:
         _watch_directory(name, config)
-        api_dir = Path(config.docs_dir) / path
-        if api_dir.exists() and api_dir not in plugin.api_dirs:
-            logger.warning(f"API directory exists: {api_dir}")
-            ans = input("Delete the directory? [yes/no] ")
-            if ans.lower() == "yes":
-                logger.info(f"Deleting API directory: {api_dir}")
-                shutil.rmtree(api_dir)
-            else:
-                logger.error("Delete the directory manually.")
-                sys.exit()
-        if not api_dir.exists():
-            msg = f"Making API directory: {api_dir}"
-            logger.info(msg)
-            api_dir.mkdir()
-            plugin.api_dirs.append(api_dir)
+
+        for path_ in _split_path(path, plugin):
+            api_dir = Path(config.docs_dir) / path_
+            _mkdir(api_dir, plugin.api_dirs)
+
         return []
 
     mkapi.nav.create(config.nav, lambda *args: mkdir(args[0], args[1]))
-    mkdir("", plugin.config.src_dir)
 
 
 def _update_nav(config: MkDocsConfig, plugin: MkAPIPlugin) -> None:
@@ -232,22 +257,22 @@ def _update_nav(config: MkDocsConfig, plugin: MkAPIPlugin) -> None:
 
     def _create_page(name: str, path: str, filters: list[str]) -> str:
         uri = name.replace(".", "/")
-        suffix = "/README.md" if is_package(name) else ".md"
+        object_path, source_path = _split_path(path, plugin)
 
-        object_uri = f"{path}/{uri}{suffix}"
+        suffix = "/README.md" if is_package(name) else ".md"
+        object_uri = f"{object_path}/{uri}{suffix}"
         abs_path = Path(config.docs_dir) / object_uri
 
         if object_uri not in plugin.pages:
             plugin.pages[object_uri] = Page(name, abs_path, filters, "object")
 
-        source_uri = f"{plugin.config.src_dir}/{uri}.md"
+        source_uri = f"{source_path}/{uri}.md"
         abs_path = Path(config.docs_dir) / source_uri
 
         if source_uri not in plugin.pages:
             plugin.pages[source_uri] = Page(name, abs_path, filters, "source")
 
-        n = len(plugin.pages)
-        spinner.text = f"Collecting modules [{n:>3}]: {name}"
+        spinner.text = f"Collecting modules [{len(plugin.pages):>3}]: {name}"
 
         return object_uri
 

tests/test_globals.py

@@ -8,7 +8,6 @@
     _iter_imports_from_import_from,
     _iter_objects_from_all,
     get_all,
-    get_all_from_ast,
     get_all_from_importlib,
     get_fullname,
     get_globals,

tests/test_pages.py

@@ -95,7 +95,7 @@ def test_create_source_markdown_failure(tmpdir: Path):
     assert "!!! failure" in m
 
 
-@pytest.fixture()
+@pytest.fixture
 def prepare(tmpdir: Path):
     api = Path(tmpdir) / "api/a.md"
     src = Path(tmpdir) / "src/b.md"
@@ -108,12 +108,12 @@ def prepare(tmpdir: Path):
     return page, obj, src
 
 
-@pytest.fixture()
+@pytest.fixture
 def page(prepare):
     return prepare[0]
 
 
-@pytest.fixture()
+@pytest.fixture
 def src(prepare):
     return prepare[2]
 
@@ -161,3 +161,11 @@ def test_convert_source(src, page):
     assert '<span class="mkapi-docs-link">[[A]](../../api/a.md#mkapi.objects' in m
     assert "``` {.python .mkapi-source}" in m
     assert "class Attribute(Member):## __mkapi__.mkapi.objects.Attribute" in m
+
+    es = ["admonition", "attr_list", "md_in_html", "pymdownx.superfences"]
+    h = markdown.markdown(m, extensions=es)
+    assert '<h2 class="mkapi-dummy-heading" id="mkapi.objects.Object">' in h
+
+    h = convert_source(h, page, "AAA")
+    assert "mkapi-dummy-heading" not in h
+    assert '<a href="../../../api/a/#mkapi.objects.is_empty">[AAA]</a></span>' in h

tests/test_plugins.py

@@ -55,8 +55,8 @@ def test_nav(mkdocs_config: MkDocsConfig):
     for item in nav:
         if isinstance(item, dict):
             nav_dict.update(item)
-    assert nav_dict["API"] == "$api/mkapi.**"
-    assert nav_dict["Examples"] == "$api/examples.**"
+    assert nav_dict["API"] == "$api:src/mkapi.**"
+    assert nav_dict["Examples"] == "$api:src/examples.**"
     # assert nav_dict["Schemdraw"] == "$api/schemdraw.***"
     # assert nav_dict["Polars"] == "$api/polars.***"
     # assert nav_dict["Altair"] == "$api/altair.***"