docs: show module documentation before submodules (#34258)

Currently, the Spack docs show documentation for submodules *before* documentation for
submodules on package doc pages. This means that if you put docs in `__init__.py` in
some package, the docs in there will be shown *after* the docs for all submodules of the
package instead of at the top as an intro to the package. See, e.g.,
[the lockfile docs](https://spack.readthedocs.io/en/latest/spack.environment.html#module-spack.environment),
which should be at the
[top of that page](https://spack.readthedocs.io/en/latest/spack.environment.html).

- [x] add the `--module-first` option to sphinx so that it generates module docs at top of page.

1 files changed, 1 insertions, 0 deletions

diff --git a/lib/spack/docs/conf.py b/lib/spack/docs/conf.py
index 55848106de..cbac5a4f4d 100644
--- a/lib/spack/docs/conf.py
+++ b/lib/spack/docs/conf.py
@@ -74,6 +74,7 @@ apidoc_args = [
     "--force",  # Overwrite existing files
     "--no-toc",  # Don't create a table of contents file
     "--output-dir=.",  # Directory to place all output
+    "--module-first",  # emit module docs before submodule docs
 ]
 sphinx_apidoc(apidoc_args + ["_spack_root/lib/spack/spack"])
 sphinx_apidoc(apidoc_args + ["_spack_root/lib/spack/llnl"])