Fixes

Author: couling

mkdocs/docs/assets/extra.css

@@ -0,0 +1,9 @@
+.md-typeset h1 code,
+.md-typeset h2 code,
+.md-typeset h3 code,
+.md-typeset h4 code,
+.md-typeset h5 code,
+.md-typeset h6 code
+{
+    background-color: unset;
+}

mkdocs/mkdocs.yaml

@@ -4,7 +4,7 @@ site_dir: dist/mkdocs_site
 
 # gives a link on each documentation page directly to edit that page in Github!
 repo_url: https://github.com/couling/MkdocstringsPythonGenerator
-edit_uri: edit/main/docs/
+edit_uri: edit/main/mkdocs/docs/
 
 
 # Enable the theme "Material"
@@ -17,6 +17,9 @@ theme:
     - navigation.sections
     - navigation.indexes
 
+extra_css:
+  - assets/extra.css
+
 markdown_extensions:
   - pymdownx.highlight:
       anchor_linenums: true
@@ -45,8 +48,10 @@ plugins:
           docstring_style: sphinx
 - mkdocstrings-python-generator:
     nav_heading:
-      - Reference
+      - Code Reference
     base: ../source
+    edit_uri: edit/main/source/
+    init_section_index: true
     search:
       - ../source/mkdocstrings_python_generator
 

source/mkdocstrings_python_generator/__init__.py

@@ -1,4 +1 @@
-"""
-# This is a page
-No really it's a page
-"""
+"""hello world"""

source/mkdocstrings_python_generator/files_generator.py

@@ -1,8 +1,9 @@
 import logging
 from fnmatch import fnmatch
 from pathlib import Path
-from typing import Dict, Iterable, List, NamedTuple, Optional, Tuple
 from tempfile import TemporaryDirectory
+from typing import Dict, Iterable, List, NamedTuple, Tuple
+
 from mkdocs.structure.files import File
 
 log = logging.getLogger(__name__)
@@ -34,7 +35,7 @@ class FilesGenerator:
     base_path: Path
     _temp_dir: TemporaryDirectory
 
-    def __init__(self, dest_dir: str, use_directory_urls: bool):
+    def __init__(self, dest_dir: str, use_directory_urls: bool, init_section_index: bool):
         """
         :param dest_dir: Configured mkdocs destination directory
         :param use_directory_urls: Configured mkdocs use_directory_urls
@@ -43,6 +44,7 @@ def __init__(self, dest_dir: str, use_directory_urls: bool):
         self._temp_dir = TemporaryDirectory()
         self.base_path = Path(self._temp_dir.name)
 
+        self._init_section_index = init_section_index
         self._dest_dir = dest_dir
         self._use_directory_urls = use_directory_urls
 
@@ -73,9 +75,9 @@ def generate_page(self, source_base_path: Path, source_path: Path, page_template
         with open(target_path, "xt", encoding="utf8") as page:
             page.write(
                 page_template.format(
-                    module_name=module_id[-1],
-                    printable_module_id=module_name(module_id),
-                    module_id=module_name(module_id),
+                    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),
                 )
             )
 
@@ -114,10 +116,29 @@ def generate_pages_recursive(self, source: Source, template: str) -> List[FileEn
         return entries
 
     def file_path_for_module_id(self, module_id: ModuleId) -> Path:
-        if module_id[-1] == "__init__":
+        """
+        Format a .md file path for a file
+        :param module_id: The module id
+        :return: An absolute path
+        """
+        if self._init_section_index and module_id[-1] == "__init__":
             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:
+        """
+        Get the module name for a given module_id
+
+        :param module_id: Module ID generated by the function ``module_id()``
+        :param full_name: If true, the full module name "foo.bar.baz" will be returned. Otherwise, just the last section
+            "baz" will be returned.
+        :param printable: Make adjustments for rendering this name. If false, the name must match something python
+            can import. If True it will be modified to be more pleasing on the eye.
+        """
+        if module_id[-1] == "__init__" and (not printable or self._init_section_index):
+            module_id = module_id[:-1]
+        return ".".join(module_id) if full_name else module_id[-1]
+
 
 def get_module_id(module_path: Path, base_path: Path) -> ModuleId:
     """
@@ -129,16 +150,6 @@ def get_module_id(module_path: Path, base_path: Path) -> ModuleId:
     return module_path.relative_to(base_path).with_suffix("").parts
 
 
-def module_name(module_id: ModuleId) -> str:
-    """
-    Get the module name for a given module_id
-
-    :param module_id: Module ID generated by the function ``module_id()``
-    """
-    if module_id[-1] == "__init__":
-        module_id = module_id[:-1]
-    return ".".join(module_id)
-
 
 def discover_python_files(source_dir: Path, ignore: List[str]) -> Iterable[Path]:
     """

source/mkdocstrings_python_generator/nav_util.py

@@ -91,7 +91,9 @@ def add_page_to_nav(nav_parent: list[NavItem], page: NavItem, module_id: ModuleI
         The page will be added to the nav as <nav_parent> -> "foo" -> "bar".
     :return: The added page.
     """
-    if module_id[-1] == "__init__":
+    if page.file.src_uri.endswith("README.md"):
+        # README.md is optionally used elsewhere for __init__ files to make them a section index page on the nav.
+        # Setting the nav title to None indicates this page is the index of the section.
         page.title = None
     else:
         page.title = module_id[-1]

source/mkdocstrings_python_generator/plugin.py

@@ -5,7 +5,7 @@
 from mkdocs.config import Config, base, config_options as c
 from mkdocs.config.defaults import MkDocsConfig
 from mkdocs.plugins import BasePlugin
-from mkdocs.structure.files import Files
+from mkdocs.structure.files import File, Files
 from mkdocs.structure.nav import Navigation, Page
 
 from . import files_generator, nav_util
@@ -22,8 +22,11 @@
 class GeneratePythonDocsConfig(base.Config):
     nav_heading: list[str] = c.ListOfItems(c.Type(str), default=["Reference"])
     base: str = c.Optional(c.Dir(exists=True))
+    edit_uri: str = c.Optional(c.Type(str))
+    edit_uri_template: str = c.Optional(c.Type(str))
     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="")
 
 
@@ -35,6 +38,7 @@ def on_files(self, files: Files, config: Config, **kwargs):
         self._files_generator = files_generator.FilesGenerator(
             dest_dir=config["site_dir"],
             use_directory_urls=config["use_directory_urls"],
+            init_section_index=self.config.init_section_index,
         )
         for search_path in self.config.search:
             self._files_generator.generate_pages_recursive(
@@ -65,8 +69,10 @@ def patch_config_nav(self, config: Config) -> None:
         ]
         config["nav"].append({"_ref": dummy_nav_list})
 
-    def on_page_content(self, html: str, *, page: Page, config: MkDocsConfig, files: Files) -> Optional[str]:
-        ...
+    def on_pre_page(self, page: Page, *, config: MkDocsConfig, files: Files) -> Optional[Page]:
+        if (generated_file := self._files_generator.generated_pages.get(Path(page.file.abs_src_path))) is None:
+            return
+        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)
@@ -81,3 +87,31 @@ def _cleanup(self):
         if self._files_generator is not None:
             self._files_generator.cleanup()
             self._files_generator = None
+
+    def make_edit_url(self, config: Config, file: files_generator.FileEntry) -> str:
+
+        # Frustratingly, the mkdocs function to format the edit URL is wrapped up in the constructor of Page
+        # It takes config and the File.src_uri as inputs
+        # To work around this...
+
+        # Make a dummy config with edit_uri and edit_uri_template replaced with this plugin's config.
+        if self.config.edit_uri is not None or self.config.edit_uri_template is not None:
+            dummy_config = config.copy()
+            dummy_config["edit_uri"] = self.config.edit_uri
+            dummy_config["edit_uri_template"] = self.config.edit_uri_template
+        else:
+            dummy_config = config
+
+        # 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,
+            dest_dir=dummy_config["site_dir"],
+            use_directory_urls=dummy_config["use_directory_urls"],
+        )
+
+        # Make a dummy_page page from the dummy_config and dummy_file
+        dummy_page = Page("if you can see this something broke", dummy_file, dummy_config)
+
+        # extract the edit_url
+        return dummy_page.edit_url