docs: part 1 - fix warnings in documentation generation (#2861)

**Description**
This PR removes some of the warnings when uv builds the docs
- Errors appear when generating docs about .md files not appearing in
toctree. ~~Adding content to the `providers-gen.py ` file that adds `---
orphan: true ---` to to each file.~~. Added a toctree generator to the
`providers-gen.py` file, this gets rid of the errors in the builds.
- Deletes the `_openai_compat` files, extension of PR #2849
- Adds the `files` APIs section to the `providers` toctree on the index
page
- Manually adds the `--- orphan: true ---` to the advanced apis. Ill try
to find a way to modify the providers code gen so it automatically adds
it, but this fixes the errors.
- Adds the `testing.md` to the `contributing` toctree
- Adds `starting_llama_stack_server.md` to `distributions` toctree

There are some other warnings im still looking at but this PR gets rid
of most of the toctree errors
Theres also an issue with the actual distribution-codegen that I can
investigate in another PR. Opened a bug for it here #2873

scripts/provider_codegen.py

@@ -255,22 +255,28 @@ def process_provider_registry(progress, change_tracker: ChangedPathTracker) -> N
             change_tracker.add_paths(doc_output_dir)
 
             index_content = []
-            index_content.append(f"# {api_name.title()} Providers")
-            index_content.append("")
+            index_content.append(f"# {api_name.title()} \n")
+            index_content.append("## Overview\n")
+
             index_content.append(
-                f"This section contains documentation for all available providers for the **{api_name}** API."
+                f"This section contains documentation for all available providers for the **{api_name}** API.\n"
             )
-            index_content.append("")
+
+            index_content.append("## Providers\n")
+
+            toctree_entries = []
 
             for provider_type, provider in sorted(providers.items()):
-                provider_doc_file = doc_output_dir / f"{provider_type.replace('::', '_').replace(':', '_')}.md"
+                filename = provider_type.replace("::", "_").replace(":", "_")
+                provider_doc_file = doc_output_dir / f"{filename}.md"
 
                 provider_docs = generate_provider_docs(provider, api_name)
 
                 provider_doc_file.write_text(provider_docs)
                 change_tracker.add_paths(provider_doc_file)
+                toctree_entries.append(f"{filename}")
 
-                index_content.append(f"- [{provider_type}]({provider_doc_file.name})")
+            index_content.append(f"```{{toctree}}\n:maxdepth: 1\n\n{'\n'.join(toctree_entries)}\n```\n")
 
             index_file = doc_output_dir / "index.md"
             index_file.write_text("\n".join(index_content))