docs: Pages not included in the MkDocs nav configuration

[wenzeslaus]

It is not clear to me if this is an issue, but it seems like a mild complain from MkDocs:

INFO    -  The following pages exist in the docs directory, but are not included in the "nav" configuration:
  - index.md
  - cairodriver.md
  - class_graphical.md
  - d.background.md
  - d.barscale.md
  - d.colorlist.md
  - d.colortable.md
  - d.correlate.md
  - d.erase.md
  - d.font.md
  - d.fontlist.md
  - d.frame.md
  - d.geodesic.md
  - d.graph.md
  - d.grid.md
<list of all our files follows>

I originally though it is a cute list of files, but then I scrolled to the beginning and I see that the message would not be produced if the configuration is done differently. Whatever is the right solution, it seems that the output is meant to not include this list if everything is configured correctly.

[sudhanshu112233shukla]

We can resolve the nav warnings by automating the nav configuration with mkdocs-gen-files. This will ensure all pages are included without manual updates. Would this approach align with the project’s goals?

[wenzeslaus]

The files are already generated (hence the warning). They are generated during build of the software. mkdocs-gen-files is generating the files itself. Merging the build with the mkdocs-gen-files procedure seems like too big of a step right now. Perhaps there is a way to just tell mkdocs about the files or even silence the message?

https://oprypin.github.io/mkdocs-gen-files/index.html

[sudhanshu112233shukla]

@wenzeslaus Confirming: Adding the auto-generated files to exclude in mkdocs.yml will resolve the warnings without altering the mkdocs-gen-files workflow. This tells MkDocs to ignore those files, silencing the message. I’ll submit a PR with the exact list of files to exclude. Let me know if you’d prefer a different approach!

[wenzeslaus]

Exact list would be terrible to maintain. How does the setting for look like? Is there a pattern match? Thanks for looking into it.

[sudhanshu112233shukla]

@wenzeslaus Thank you for emphasizing the importance of avoiding manual maintenance. To resolve this cleanly, we can configure the exclude section in mkdocs.yml using MkDocs’ built-in glob pattern matching. For example:
Exclude:

  "**/*.gen.md"          # Excludes files ending with `.gen.md` (e.g., `raster/r.tool.gen.md`)  
   "**/auto_generated/*"  # Ignores all files in directories like `auto_generated/`  
   "tmp_*.md"             # Skips files prefixed with `tmp_` (e.g., `tmp_draft.md`)

This setup uses ** to match any subdirectory and * for flexible naming rules, ensuring MkDocs permanently silences warnings about unlisted files. It eliminates manual list updates and scales effortlessly. Let me know we if I have to make any changes .Thank you

[wenzeslaus]

Does this exclude the files or does it include them while silencing the 'not included in the "nav" configuration' message?

[sudhanshu112233shukla]

@wenzeslaus The exclude configuration removes files entirely from the MkDocs build process, meaning they are not rendered in the final documentation site and are excluded from all processing (silencing the "not included in nav" warning). For example, adding exclude: ["**/*.gen.md"] ensures MkDocs ignores those files. If the goal is to retain the files in the build but resolve the warning, they must be explicitly added to the nav configuration (e.g., nav: ["path/to/file.gen.md"]), which includes them in the navigation structure and suppresses the message. Let me know whether you prefer excluding the files or updating the nav, and I’ll refine the PR accordingly,Thank you.

[wenzeslaus]

Simply adding all the current files to the config is not really an option, there is a lot and more are being added. Hence this issues.

[sudhanshu112233shukla]

@wenzeslaus new files auto-include themselves, and temporary ones stay hidden. No manual lists?