Fixes and documentation

Author: couling

mkdocs/docs/configuration.md

@@ -0,0 +1,41 @@
+# Configuration
+
+## Full Example
+
+For mkdocstrings-python configuration: [see here](https://mkdocstrings.github.io/python/usage/)
+
+```yaml
+
+- mkdocstrings-python-generator:
+    nav_heading:
+      - Code Reference
+    search:
+      - src/my_package
+    base: src
+    ignore:
+      - test_*
+
+    
+    edit_uri: edit/main/src/
+    init_section_index: true
+    prune_nav_prefix: my_package
+
+# This part of the config is up to you.
+- mkdocstrings:
+    handlers:
+      python:
+        ...
+```
+
+## Options
+
+| Option Name          | Description                                                                                                                                                                                                                                  | Value Type      |
+|----------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------|
+| `nav_heading`        | Describes where to place the generated files on the nav. Eg: if you want `Reference` > `Code Reference` then set `["Reference", "Code Reference"]`                                                                                           | List of Strings |
+| `search`             | Search paths to look for python files relative to mkdocs.yaml                                                                                                                                                                                | List of Strings |
+| `base`               | If different from the search paths, set this to the base directory of python files similar to might be added as `PYTHONPATH`. ⚠️ Only one base may be specified                                                                              | String          |
+| `ignore`             | List of [glob expressions](https://docs.python.org/3/library/glob.html#glob.glob) to ignore from the search. These are applied per file and so cannot specify directories.                                                                   | List of Strings |
+| `edit_uri`           | Override mkdocs [edit_uri](https://www.mkdocs.org/user-guide/configuration/#edit_uri) for generated files                                                                                                                                    | String          |
+| `edit_uri_template`  | Override mkdocs [edit_uri_template](https://www.mkdocs.org/user-guide/configuration/#edit_uri_template) for generated files                                                                                                                  | String          |
+| `init_section_index` | Some themes such as Material support [section indexes](https://squidfunk.github.io/mkdocs-material/setup/setting-up-navigation/#section-index-pages). If enabled `__init__.py` files with content will be used to define section index pages | Boolean         |
+| `prune_nav_prefix`   | If your package exists deep in some namespace you can remove specific parents from the nav keeping the nav cleaner and simpler.  Simply name the python prefix you want to prune from the nav. Eg: `foo.bar.my_namespace_package`            | String          |

mkdocs/docs/index.md

@@ -1,2 +1,41 @@
-# Mkdocstrings Python Generator
-Hello!
+# mkdocstrings-python-generator
+
+mkdocstrings-python-generator is a mkdocs plugin for generating markdown pages automatically from python source code.
+
+It is intended to fill a gap which is currently left to each user of mkdoctstings-python.  Namely: generating markdown
+files for each python file.
+
+_Note despite the name there is no affiliation between mkdocstrings and mkdocstrings-python-generator. Please try to 
+determine which plugin is to blame before posting issues here or [there](https://github.com/mkdocstrings/python)._
+
+
+## Features
+
+It's advantages over the [mkdocstrings-python recopy](https://mkdocstrings.github.io/recipes/#automatic-code-reference-pages) are:
+
+ - ✅ Easier to use (no writing code for yourself)
+ - ✅ Well formatted nav out of the box. Package names with underscores are not title case 📦
+ - ✅ Compatibility with both explicit nav defined in mkdocs.yaml and implicit nav with no definition in mkdocs.yaml
+ - ✅ Supports __init__.py files as [section indexes](https://squidfunk.github.io/mkdocs-material/setup/setting-up-navigation/#section-index-pages) if supported by the theme.
+ - ✅ Edit URI compatible with both `edit_uri` and `edit_uri_template`
+
+## Minimal Example
+
+See [Configuration](../configuration/) for more detail
+
+
+```yaml
+# Configure mkdocstrings-python
+- mkdocstrings:
+    handlers:
+      python:
+        options:
+          show_submodules: false
+
+# Configure mkdocstrings-python-generator
+- mkdocstrings-python-generator:
+    search:
+      # Path to your source directory relative to mkdocs.yaml directory.
+      - src/
+
+```

mkdocs/mkdocs.yaml

@@ -6,6 +6,9 @@ site_dir: dist/mkdocs_site
 repo_url: https://github.com/couling/MkdocstringsPythonGenerator
 edit_uri: edit/main/mkdocs/docs/
 
+nav:
+  - Welcome: index.md
+  - Configuration: configuration.md
 
 # Enable the theme "Material"
 theme:
@@ -54,6 +57,7 @@ plugins:
     init_section_index: true
     search:
       - ../source/mkdocstrings_python_generator
+    prune_nav_prefix: mkdocstrings_python_generator
 
 watch:
   - docs

pyproject.toml

@@ -11,7 +11,7 @@ packages = [
 
 [tool.poetry.dependencies]
 python = "^3.7"
-mkdocstrings-python = "^1.1.2"
+mkdocstrings-python = "^1.0.0"
 mkdocs = "^1.4.0"
 
 
@@ -46,5 +46,5 @@ mkdocstrings-python-generator = "mkdocstrings_python_generator.plugin:GeneratePy
 
 
 [tool.yapf]
-based_on_style="facebook"
+based_on_style="pep8"
 column_limit=120

source/mkdocstrings_python_generator/__init__.py

@@ -1 +0,0 @@
-"""hello world"""

source/mkdocstrings_python_generator/files_generator.py

@@ -15,16 +15,31 @@
 
 
 class FileEntry(NamedTuple):
+    """Stores key information about a markdown/python file internal to mkdocs-python-genfiles"""
     source_file_path: Path
+    """Absolute path to python source file on disk"""
     doc_file_path: Path
+    """Absolute path to markdown file on disk"""
     module_id: ModuleId
+    """Abstract representation of a python module similar to it's dot-part string divided as a tuple
+    
+    Importantly, a package __init__ file for package foo.bar will be ``("foo", "bar", "__init__")``"""
     file: File
+    """Mkdocs File object for use by mkdocs only"""
 
 
 class Source(NamedTuple):
+    """Source of python files"""
     base_path: Path
+    """Root of the python files
+    
+    This is as python might see in PYTHONPATH"""
     dir_path: Path
+    """Directory to search
+    
+    May be the same as base_path but may also be a subdirectory of it, eg: to avoid unit tests."""
     ignore: List[str]
+    """List of glob expressions for files and directories to ignore."""
 
 
 class FilesGenerator:
@@ -78,20 +93,17 @@ def generate_page(self, source_base_path: Path, source_path: Path, page_template
                     module_name=self.module_name(module_id, full_name=False, printable=True),
                     printable_module_id=self.module_name(module_id, full_name=True, printable=True),
                     module_id=self.module_name(module_id, full_name=True, printable=False),
-                )
-            )
-
-        entry = FileEntry(
-            source_file_path=source_path,
-            doc_file_path=target_path,
-            module_id=module_id,
-            file=File(
-                str(target_path.relative_to(self.base_path)),
-                src_dir=str(self.base_path),
-                dest_dir=self._dest_dir,
-                use_directory_urls=self._use_directory_urls,
-            )
-        )
+                ))
+
+        entry = FileEntry(source_file_path=source_path,
+                          doc_file_path=target_path,
+                          module_id=module_id,
+                          file=File(
+                              str(target_path.relative_to(self.base_path)),
+                              src_dir=str(self.base_path),
+                              dest_dir=self._dest_dir,
+                              use_directory_urls=self._use_directory_urls,
+                          ))
         self.generated_pages[entry.doc_file_path.absolute()] = entry
         return entry
 
@@ -122,7 +134,7 @@ def file_path_for_module_id(self, module_id: ModuleId) -> Path:
         :return: An absolute path
         """
         if self._init_section_index and module_id[-1] == "__init__":
-            module_id = module_id[:-1] + ("README.md",)
+            module_id = module_id[:-1] + ("README.md", )
         return Path(self.base_path, "_ref", *module_id).with_suffix(".md")
 
     def module_name(self, module_id: ModuleId, full_name: bool, printable: bool) -> str:
@@ -150,7 +162,6 @@ def get_module_id(module_path: Path, base_path: Path) -> ModuleId:
     return module_path.relative_to(base_path).with_suffix("").parts
 
 
-
 def discover_python_files(source_dir: Path, ignore: List[str]) -> Iterable[Path]:
     """
     Discover python files recursively from a directory

source/mkdocstrings_python_generator/nav_util.py

@@ -21,15 +21,16 @@ class PageEntry(NamedTuple):
     file: FileEntry
 
 
-def build_reference_nav(
-    nav: Navigation, generated_pages: Dict[Path, FileEntry], section_heading: List[str], config: MkDocsConfig
-) -> None:
+def build_reference_nav(nav: Navigation, generated_pages: Dict[Path, FileEntry], section_heading: List[str],
+                        prune_prefix_package: ModuleId, config: MkDocsConfig) -> None:
     """
     [re]build parts of the navigation which were created through dynamic generation
     :param nav: Navigation
     :param generated_pages: generated_pages from files_generator
     :param section_heading: List of titles indicating where to put the generated pages. Eg ``["Reference"]``.
     :param config: MkdocsConfig
+    :param prune_prefix_package: Module id to remove if it exists from every pacakge in the nav.
+        This is typically useful for pruning namespaces from the nav
     :return:
     """
     generated_pages = generated_pages.copy()
@@ -45,11 +46,27 @@ def build_reference_nav(
     pages_to_add.sort(key=lambda item: item.file.module_id)
 
     for page, entry in pages_to_add:
-        add_page_to_nav(nav.items, page, (*section_heading, *entry.module_id))
+        add_page_to_nav(nav.items, page, nav_path_for_module(section_heading, prune_prefix_package, entry))
 
     patch_nav_refs(nav)
 
 
+def nav_path_for_module(section_heading: List[str], prune_prefix_package: ModuleId,
+                        entry: FileEntry) -> Tuple[str, ...]:
+    """
+    Calculate the position of a module in the nav
+    :param section_heading: The section heading for reference documentation
+    :param prune_prefix_package: Configured prefix to prune from every module
+    :param entry: The module's entry
+    """
+    prefix_length = len(prune_prefix_package)
+    if entry.module_id[:prefix_length] == prune_prefix_package:
+        module_id = entry.module_id[prefix_length:]
+    else:
+        module_id = entry.module_id
+    return *section_heading, *module_id
+
+
 def ensure_nav_section(nav_parent: List[NavItem], section_path: Union[List[str], Tuple[str, ...]]) -> Section:
     """Ensure a specific nav section exists and return it
 

source/mkdocstrings_python_generator/plugin.py

@@ -27,7 +27,7 @@ class GeneratePythonDocsConfig(base.Config):
     search: list[str] = c.ListOfItems(c.Dir(exists=True))
     ignore: list[str] = c.ListOfItems(c.Type(str), default=["test", "tests", "__main__.py"])
     init_section_index: bool = c.Type(bool, default=False)
-    flatten_nav_package: str = c.Type(str, default="")
+    prune_nav_prefix: str = c.Type(str, default="")
 
 
 class GeneratePythonDocs(BasePlugin[GeneratePythonDocsConfig]):
@@ -63,10 +63,9 @@ def patch_config_nav(self, config: Config) -> None:
         The only solid reason for this to exist is to suppress warnings from mkdocs.  Without it, mkdocs would warn that
         generated markdown files were not in the nav.
         """
-        dummy_nav_list = [
-            {".".join(module.module_id): module.file.src_path}
-            for module in self._files_generator.generated_pages.values()
-        ]
+        dummy_nav_list = [{
+            ".".join(module.module_id): module.file.src_path
+        } for module in self._files_generator.generated_pages.values()]
         config["nav"].append({"_ref": dummy_nav_list})
 
     def on_pre_page(self, page: Page, *, config: MkDocsConfig, files: Files) -> Optional[Page]:
@@ -75,7 +74,13 @@ def on_pre_page(self, page: Page, *, config: MkDocsConfig, files: Files) -> Opti
         page.edit_url = self.make_edit_url(config, generated_file)
 
     def on_nav(self, nav: Navigation, *, config: MkDocsConfig, files: Files) -> None:
-        nav_util.build_reference_nav(nav, self._files_generator.generated_pages, self.config.nav_heading, config)
+        nav_util.build_reference_nav(
+            nav=nav,
+            generated_pages=self._files_generator.generated_pages,
+            section_heading=self.config.nav_heading,
+            prune_prefix_package=tuple(self.config.prune_nav_prefix.split(".")),
+            config=config,
+        )
 
     def on_post_build(self, *, config: MkDocsConfig) -> None:
         self._cleanup()
@@ -104,8 +109,8 @@ def make_edit_url(self, config: Config, file: files_generator.FileEntry) -> str:
 
         # Make a dummy file with the python source file as src_uri instead of the .md file
         dummy_file = File(
-            path=str(file.source_file_path.relative_to(Path(self.config.base))),
-            src_dir=self.config.base,
+            path=("/".join(file.module_id)) + ".py",
+            src_dir="",
             dest_dir=dummy_config["site_dir"],
             use_directory_urls=dummy_config["use_directory_urls"],
         )
@@ -114,4 +119,4 @@ def make_edit_url(self, config: Config, file: files_generator.FileEntry) -> str:
         dummy_page = Page("if you can see this something broke", dummy_file, dummy_config)
 
         # extract the edit_url
-        return dummy_page.edit_url
+        return dummy_page.edit_url