Recommend new features for generating stubs

Author: oprypin

docs/quickstart/migrate.md

@@ -123,7 +123,7 @@ But if you make this change by itself, MkDocs will no longer be able to group th
 So the navigation now has to be specified fully explicitly. As we've been generating the stub files, let's also generate the nav file itself. The file `docs/gen_doc_stubs.py` will gain these additions:
 
 ???+ example "docs/gen_doc_stubs.py"
-    ```python hl_lines="10 15 21-22"
+    ```python hl_lines="10 15 25-26"
     --8<-- "examples/migrated/docs/gen_doc_stubs_nav.py"
     ```
 

examples/migrated/docs/gen_doc_stubs.py

@@ -10,6 +10,10 @@
 for typ in root.walk_types():
     # Use the file name "Foo/Bar/index.md"
     filename = '/'.join(typ.abs_id.split('::') + ['index.md'])
-    # Make a file with the content "::: Foo::Bar\n"
+    # Make a file with the content "# ::: Foo::Bar\n"
     with mkdocs_gen_files.open(filename, 'w') as f:
-        print(f'::: {typ.abs_id}', file=f)
+        print(f'# ::: {typ.abs_id}', file=f)
+
+    # Link to the type itself when clicking the "edit" button on the page.
+    if typ.locations:
+        mkdocs_gen_files.set_edit_path(filename, typ.locations[0].url)

examples/migrated/docs/gen_doc_stubs_nav.py

@@ -13,9 +13,13 @@
 for typ in root.walk_types():
     # Use the file name "Foo/Bar.md"
     filename = '/'.join(typ.abs_id.split('::')) + '.md'
-    # Make a file with the content "::: Foo::Bar\n"
+    # Make a file with the content "# ::: Foo::Bar\n"
     with mkdocs_gen_files.open(filename, 'w') as f:
-        print(f'::: {typ.abs_id}', file=f)
+        print(f'# ::: {typ.abs_id}', file=f)
+
+    # Link to the type itself when clicking the "edit" button on the page
+    if typ.locations:
+        mkdocs_gen_files.set_edit_path(filename, typ.locations[0].url)
 
     # Append to the nav: "    * [Bar](Foo/Bar.md)"
     indent = '    ' * typ.abs_id.count('::')