literate-nav + section-index + gen-files

[pawamoy]

Hello @oprypin, hope you're doing well :slightly_smiling_face:

I'm trying to generate a nav with gen-files, to be used by literate-nav, with a section index. Is it possible? What is the gen-files equivalent of this nav?

* [Borgs](borgs/index.md)
    * [Bar](borgs/bar.md)
    * [Foo](borgs/foo.md)

I'm currently trying this:

"""Generate the code reference pages and navigation."""

from pathlib import Path

import mkdocs_gen_files

nav = mkdocs_gen_files.Nav()

for path in sorted(Path("src").glob("**/*.py")):
    module_path = path.relative_to("src").with_suffix("")
    doc_path = path.relative_to("src", "griffe").with_suffix(".md")
    full_doc_path = Path("reference", doc_path)

    # --------------> INTERESTING PART <-------------------
    parts = list(module_path.parts)
    if parts[-1] == "__init__":
        parts = parts[:-1]
    elif parts[-1] == "__main__":
        continue
    nav_parts = list(parts)
    print(nav_parts, doc_path)
    nav[nav_parts] = doc_path
    # --------------> END OF INTERESTING PART <------------

    with mkdocs_gen_files.open(full_doc_path, "w") as fd:
        ident = ".".join(parts)
        print("::: " + ident, file=fd)

    mkdocs_gen_files.set_edit_path(full_doc_path, path)

with mkdocs_gen_files.open("reference/SUMMARY.md", "w") as nav_file:
    nav_file.writelines(nav.build_literate_nav())

But it gives me this nav:

...and prints this to stdout:

INFO     -  Building documentation...
['griffe'] __init__.md
['griffe', 'cli'] cli.md
['griffe', 'collections'] collections.md
['griffe', 'dataclasses'] dataclasses.md
['griffe', 'docstrings'] docstrings/__init__.md
['griffe', 'docstrings', 'dataclasses'] docstrings/dataclasses.md
['griffe', 'docstrings', 'google'] docstrings/google.md
['griffe', 'docstrings', 'markdown'] docstrings/markdown.md
['griffe', 'docstrings', 'numpy'] docstrings/numpy.md
['griffe', 'docstrings', 'parsers'] docstrings/parsers.md
['griffe', 'docstrings', 'rst'] docstrings/rst.md
['griffe', 'docstrings', 'utils'] docstrings/utils.md
['griffe', 'encoders'] encoders.md
['griffe', 'extended_ast'] extended_ast.md
['griffe', 'extensions'] extensions/__init__.md
['griffe', 'extensions', 'base'] extensions/base.md
['griffe', 'loader'] loader.md
['griffe', 'logger'] logger.md
['griffe', 'visitor'] visitor.md

I tried replacing the __init__.md filenames by index.md, but it gives the same result with "Index" in the nav instead of "init".

[oprypin]

Seems fully correct actually, the only thing I'd guess is that section-index plugin isn't actually running.

In any case, to exclude mystery about gen-files from the equation, please simply run the generator script directly. Then you see its output for real.

The only other thing -- please share your mkdocs.yml and I'll be able to check this in an hour

[pawamoy]

Oh damn... The section-index plugin is not listed in my mkdocs config, nor my deps... Thanks for your help 🙇