Show the new nav generator from mkdocs-gen-files

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 25-26"
+    ```python hl_lines="10 15 25 28-29"
     --8<-- "examples/migrated/docs/gen_doc_stubs_nav.py"
     ```
 

examples/migrated/docs/gen_doc_stubs.py

@@ -4,15 +4,15 @@
 import mkdocs_gen_files
 
 # Get the documentation root object
-root = mkdocs_gen_files.config['plugins']['mkdocstrings'].get_handler('crystal').collector.root
+root = mkdocs_gen_files.config["plugins"]["mkdocstrings"].get_handler("crystal").collector.root
 
 # For each type (e.g. "Foo::Bar")
 for typ in root.walk_types():
     # Use the file name "Foo/Bar/index.md"
-    filename = '/'.join(typ.abs_id.split('::') + ['index.md'])
+    filename = "/".join(typ.abs_id.split("::") + ["index.md"])
     # 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)
+    with mkdocs_gen_files.open(filename, "w") as f:
+        print(f"# ::: {typ.abs_id}", file=f)
 
     # Link to the type itself when clicking the "edit" button on the page.
     if typ.locations:

examples/migrated/docs/gen_doc_stubs_nav.py

@@ -4,23 +4,26 @@
 import mkdocs_gen_files
 
 # Get the documentation root object
-root = mkdocs_gen_files.config['plugins']['mkdocstrings'].get_handler('crystal').collector.root
+root = mkdocs_gen_files.config["plugins"]["mkdocstrings"].get_handler("crystal").collector.root
 
-# Start a navigation file (to be filled as we go along)
-nav = mkdocs_gen_files.open('SUMMARY.md', 'a')
+# Start a navigation collection (to be filled as we go along)
+nav = mkdocs_gen_files.Nav()
 
 # For each type (e.g. "Foo::Bar")
 for typ in root.walk_types():
     # Use the file name "Foo/Bar.md"
-    filename = '/'.join(typ.abs_id.split('::')) + '.md'
+    filename = "/".join(typ.abs_id.split("::")) + ".md"
     # 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)
+    with mkdocs_gen_files.open(filename, "w") as 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('::')
-    print(indent + f'* [{typ.name}]({filename})', file=nav)
+    nav[typ.abs_id.split("::")] = filename
+
+# Append the nav to a "literate nav" file
+with mkdocs_gen_files.open("SUMMARY.md", "a") as nav_file:
+    nav_file.writelines(nav.build_literate_nav())

examples/migrated/docs/requirements.txt

@@ -39,9 +39,9 @@ markupsafe==1.1.1
     #   mkdocstrings-crystal
 mkdocs-autorefs==0.1.1
     # via mkdocstrings
-mkdocs-gen-files==0.3.1
+mkdocs-gen-files==0.3.2
     # via -r requirements.in
-mkdocs-literate-nav==0.3.0
+mkdocs-literate-nav==0.3.1
     # via -r requirements.in
 mkdocs-material-extensions==1.0.1
     # via mkdocs-material