Document recent changes to config finding

Summary:
Documents:
* the additional config-like files we now look for in upward search,
* detection of flat and src project layouts,
* the dump-config command.

I struggled a bit to articulate what was going on with project roots and import roots. Happy to take suggestions for how to make this clearer.

Reviewed By: migeed-z

Differential Revision: D74289623

fbshipit-source-id: cf27339ffd6e85e880e6a8736d473788fa9495fd

Author: rchen152

website/docs/configuration.mdx

@@ -52,10 +52,17 @@ correspond to different but useful ways we expect most people to interact with P
 ## Configuration Finding
 
 In both project checking mode and single-file checking mode (see [Type Checking Modes](#type-checking-modes)
-for more info), we may perform an upward file search to find a
-configuration file if one is not provided with `-c`/`--config`. We each directory
-from the 'start location' to the filesystem root, looking first for `pyrefly.toml` then `pyproject.toml`, in
-the same directory before looking at its parent.
+for more info), we attempt to find a *project root* from which to check each file, both for reading
+config options and for import resolution  (see [Import Root](./import-resolution.mdx#import-root)). The
+project root is typically the directory containing the configuration file. More precisely:
+
+1. If a configuration file is provided with `-c`/`--config`, we use its containing directory.
+1. Otherwise, we perform an upward file search from the 'start location' to the filesystem root,
+   looking in each directory for any of the following files: `pyrefly.toml`, `pyproject.toml`,
+   `setup.py`, `mypy.ini`, and `pyrightconfig.json`. If we find one, we use the current directory.
+
+Note that only `pyrefly.toml` and `pyproject.toml` are parsed for config options, but we look for
+additional files that mark the root of a project to aid import resolution.
 
 For project checking mode, the 'start location' is current working directory. For single-file checking mode,
 the start location is the directory containing each file to be type checked, and
@@ -131,12 +138,12 @@ type checked file is imported by another type checked file, we check all search
 determine how to import it.
 
 - Type: list of directories specifying the root
-- Default: `["."]`
+- Default: [import root](./import-resolution.mdx#import-root)
 - Flag equivalent: `--search-path`
 - ENV equivalent: `PYREFLY_SEARCH_PATH`
 - Equivalent configs: `extraPaths` in Pyright, `mypy_path` in mypy
 - Notes:
-  - We automatically append `"."` (the directory containing the
+  - We automatically append an import root (typically the directory containing the
     configuration file) to the `search_roots` when type checking as a sensible
     default and last attempt at an import.
   - Libraries should not be listed here, since they may override `typeshed`

website/docs/import-resolution.mdx

@@ -25,9 +25,8 @@ directory, and more dots (e.g. `..other.file`) will continue to walk upward.
 For absolute imports, Pyrefly uses the following import strategy:
 
 1. Try to import from each entry in [`search_path`](./configuration.mdx#search_path) in the order they appear
-   using the module finding strategy. a. NOTE: we append the config file's
-   directory to `search_path` automatically when using a config file as a
-   sensible last-resort for attempting an import.
+   using the module finding strategy. a. NOTE: we append an [import root](#import-root) to `search_path`
+   automatically when using a config file as a sensible last-resort for attempting an import.
 2. Try to import from `typeshed`.
 3. Try to find a stub package corresponding to the import we're trying to resolve in
    [`site_package_path`](./configuration.mdx#site_package_path).
@@ -43,6 +42,17 @@ See [Site Package Path Typing Rules](#site-package-path-typing-rules) for more i
 modules are valid imports from [`site_package_path`](./configuration.mdx#site_package_path), and
 how to override that behavior.
 
+### Import Root
+
+Pyrefly automatically appends an *import root* to the search path. This is the directory that
+importable Python packages live in, determined from the
+[project root](./configuration.mdx#configuration-finding) and layout.
+Pyrefly auto-detects import roots for two common project layouts:
+
+* Src layout, assumed when there is a `src/` directory directly inside the project root. `src/` is
+  the import root.
+* Flat layout, the default. The project root is the import root.
+
 ### Site Package Path Typing Rules
 
 We respect typing rules as defined by the typing spec for
@@ -83,3 +93,9 @@ imports by first searching for a relevant `-stubs` package, then by looking at
 the non-stubs package's `.pyi` files, then falls back to a `.py` file. See
 [Absolute Imports](#absolute-imports) for details on when non-stubs packages
 are allowed to be used for types, and how you can override that behavior.
+
+## Debugging Import Issues
+
+Pyrefly has a `dump-config` command that dumps the import-related config options it is using for
+each file it is checking. To use it, simply replace `check` with `dump-config` in your
+command-line invocation.