Update the site content: organize it and move paragraphs

docs/FAQ.md

@@ -14,71 +14,6 @@ and debug each occurrence. Typically an undeclared dependency can be fixed in a
 - A true undeclared dependency is fixed by _declaring_ it, e.g. adding it to your `pyproject.toml` or similar.
 - If you disagree with FawltyDeps' classification, you can always use `--ignore-undeclared` to silence the error. If you're sure this dependency should not have been reported by FawltyDeps, you may consider filing a bug report.
 
-### How not to display tools like `black` and `pylint` in _unused dependencies_?
-
-By default, all packages declared as dependencies by your project are included
-in the FawltyDeps analysis, even if they only contain tools that were not meant
-to be `import`ed, but rather meant to be run by, say, in a pre-commit hook or a
-CI script. In such cases you may use either:
-
-```sh
-fawltydeps --ignore-unused black pylint
-```
-
-or add an equivalent directive to the FawltyDeps configuration in your
-`pyproject.toml` (see below).
-
-### How can I store my `fawltydeps` command line options in a configuration file?
-
-You can run:
-
-```sh
-fawltydeps --generate-toml-config
-```
-
-to generate a `[tool.fawltydeps]` section with the current configuration that
-you can then directly copy into your `pyproject.toml`. Options that have their
-default value are commented in this output, so you have quickly see where your
-settings differ from the FawltyDeps defaults.
-
-This also works together with other command line options, so for example in the
-previous question, you could add `--generate-toml-config` to the command line
-(i.e. run `fawltydeps --ignore-unused black pylint --generate-toml-config`),
-to get this:
-
-```toml
-[tool.fawltydeps]
-# Default options are commented...
-ignore_unused = ["black", "pylint"]
-```
-
-### How to use FawltyDeps in a monorepo?
-
-Running `fawltydeps` without arguments at the root of a monorepo
-will most likely not give you a useful result:
-it will collect dependencies and import statements from across the _entire_ monorepo.
-The produced report may be overwhelming and at the same time not granular enough.
-
-Instead, you should run FawltyDeps for each package separately.
-This collects dependencies and import statements for one package at a time.
-
-Having:
-
-```sh
-├ lib1
-| ├ pyproject.toml
-| ├ ....
-├ lib2
-| ├ pyproject.toml
-| ├ ....
-```
-
-run for each `libX`:
-
-```sh
-fawltydeps libX
-```
-
 ### Why must FawltyDeps run in the same Python environment as my project dependencies?
 
 (This is no longer true since FawltyDeps v0.11: FawltyDeps should be able to
@@ -139,39 +74,3 @@ To solve this problem, make sure that `scikit-learn` is installed in a Python
 environment that belongs to your project. Alternatively, you can use the
 `--pyenv` option to point at a Python environment where `scikit-learn` and your
 other dependencies are installed.
-
-### How can I pass Python code to FawltyDeps via standard input?
-
-The `--code` argument accepts a single hyphen (`-`) as a special value meaning
-that code should be read from standard input. When using this you may pipe or
-redirect your Python code into FawltyDeps like this:
-
-```sh
-cat some/source/of/python/code | fawltydeps --code -
-# or
-fawltydeps --code - < some/source/of/python/code
-```
-
-You can also use this directly in the terminal to e.g. have FawltyDeps analyze
-some Python code that is in your clipboard:
-
-```sh
-fawltydeps --code -
-# FawltyDeps waits for code on stdin; paste from your clipboard,
-# then press Ctrl+D to signal EOF (end-of-file).
-```
-
-### Can I use FawltyDeps as a pre-commit hook?
-
-Yes! Assuming that you already use the [pre-commit](https://pre-commit.com)
-tool, you can add something like this to your project's
-`.pre-commit-config.yaml`:
-
-```yaml
-repos:
-  - repo: https://github.com/tweag/FawltyDeps
-    rev: v0.17.0
-    hooks:
-      - id: check-undeclared
-      - id: check-unused
-```

docs/explanation.md

@@ -18,7 +18,8 @@ When FawltyDeps looks for undeclared and unused dependencies, it needs to match
 declared in your project configuration.
 
 To solve this, FawltyDeps uses a sequence of resolvers (aka. mapping strategies)
-to determine which Python packages provide which import names. The diagram below
+to determine which Python packages provide which import names. For more details,
+check [FawltyDeps mapping strategy blogpost](https://www.tweag.io/blog/2023-09-21-fawltydeps-mapping-strategy/). The diagram below
 shows the dependencies' flow through the sequence of mappings supported by
 FawltyDeps (each of which is introduced in the following subsections):
 
@@ -241,27 +242,9 @@ We've introduced a `DEFAULT_IGNORE_UNUSED` list, which includes various
 categories of commonly used development tools and dependencies.
 FawltyDeps can automatically ignore these dependencies when checking for unused
 imports. For the complete list, please see the `DEFAULT_IGNORE_UNUSED`
-variable in the [`fawltydeps/settings.py`](./fawltydeps/settings.py) file
+variable in the `fawltydeps/settings.py` file
 in the repository. If you have additional dependencies that you want to exclude
 from the check for unused imports, you can use the `--ignore-unused` option
 to customize the ignore list. By providing your own list of dependencies with
 this option, you can effectively overwrite the default list. For example:
 `--ignore-unused black mypy some_other_module`
-
-### Output formats
-
-The default output from FawltyDeps is a summary outlining the relevant
-dependencies found (according to the selected actions).
-However you can also ask for more information from FawltyDeps:
-
-- `--summary`: Default (human-readable) summary output
-- `--detailed`: Longer (human-readable) output that includes the location of
-  the relevant dependencies.
-- `--json`: Verbose JSON-formatted output for other tools to consume and
-  process further.
-
-Only one of these options can be used at a time.
-
-### More help
-
-Run `fawltydeps --help` to get the full list of available options.

docs/how_to_guides.md

@@ -1,6 +1,6 @@
 # How-to guides
 
-## Not displaying development tools
+## Ignore development tools
 
 How not to display tools like `black` and `pylint` in _unused dependencies_?
 
@@ -16,7 +16,7 @@ fawltydeps --ignore-unused black pylint
 or add an equivalent directive to the FawltyDeps configuration in your
 `pyproject.toml` (see below).
 
-## Storing `fawltydeps` options in a configuration file.
+## Store `fawltydeps` options in a configuration file.
 
 You can run:
 

docs/index.md

@@ -2,6 +2,8 @@
 
 FawltyDeps is an open-source Python tool that checks your dependencies to ensure they are being used correctly. It helps you identify any dependencies listed in your `requirements.txt` or `pyproject.toml` that are not actually used in your codebase, and vice versa.
 
+![FawltyDeps demo](images/fawltydeps_demo_tqdm.gif)
+
 ## Features
 
 - Detect unused dependencies

docs/reference.md

@@ -1,5 +1,23 @@
 # References
 
+## Installation
+
+### Requirements
+
+- Python 3.7 or higher
+
+### Installation
+
+The library is distributed with PyPI, so simply:
+
+```sh
+pip install fawltydeps
+```
+
+or any other way to install Python packages from PyPI should be enough to make it available in your environment.
+
+Consider adding `fawltydeps` to your development dependencies, to help you catch undeclared and unused dependencies in your projects.
+
 ## Usage
 
 To check the project in the current directory run:
@@ -10,7 +28,7 @@ fawltydeps
 
 This will find imports in all the Python code under the current directory,
 extract dependencies declared by your project, and then report
-[_undeclared_ and _unused_ dependencies](#key-concepts).
+[_undeclared_ and _unused_ dependencies](explanation.md#key-concepts).
 
 ### Available Actions
 
@@ -126,7 +144,7 @@ Here is a complete list of configuration directives we support:
   The default is a list including common development tools. However, you have the
   flexibility to overwrite this list according to your project's specific requirements.
   For the complete default list, please see the `DEFAULT_IGNORE_UNUSED`
-  variable in the [`fawltydeps/settings.py`](./fawltydeps/settings.py) file
+  variable in the `fawltydeps/settings.py` file
   in the repository.
 - `deps_parser_choice`: Manually select which format to use for parsing
   declared dependencies. Must be one of `"requirements.txt"`, `"setup.py"`,
@@ -148,9 +166,9 @@ Here is a complete list of configuration directives we support:
   - `1`: `INFO`-level log messages and above are shown.
   - `2`: All log messages (including `DEBUG`) are shown.
 - `custom_mapping_file`: Paths to files containing user-defined mapping.
-  Expected file format is defined in the User-defined mapping [section](#user-defined-mapping).
+  Expected file format is defined in the User-defined mapping [section](explanation.md#user-defined-mapping).
 - `[tool.fawltydeps.custom_mapping]`: Section in the configuration, under which a custom mapping
-  can be added. Expected format is described in the User-defined mapping [section](#user-defined-mapping).
+  can be added. Expected format is described in the User-defined mapping [section](explanation.md#user-defined-mapping).
 
 ### Environment variables
 
@@ -167,3 +185,21 @@ set `fawltydeps_output_format=json` in FawltyDeps' environment.
 - Configuration in `pyproject.toml` override only the ultimate hardcoded defaults.
 - The ultimate defaults when no cutomizations takes place are hardcoded inside
   FawltyDeps, and are documented above.
+
+### Output formats
+
+The default output from FawltyDeps is a summary outlining the relevant
+dependencies found (according to the selected actions).
+However you can also ask for more information from FawltyDeps:
+
+- `--summary`: Default (human-readable) summary output
+- `--detailed`: Longer (human-readable) output that includes the location of
+  the relevant dependencies.
+- `--json`: Verbose JSON-formatted output for other tools to consume and
+  process further.
+
+Only one of these options can be used at a time.
+
+## More help
+
+Run `fawltydeps --help` to get the full list of available options.