ENH: more intuitive profiling-target selection

CHANGELOG.rst

@@ -11,7 +11,8 @@ Changes
 * FIX: Fixed explicit profiling of class methods; added handling for profiling static, bound, and partial methods, ``functools.partial`` objects, (cached) properties, and async generator functions
 * FIX: Fixed namespace bug when running ``kernprof -m`` on certain modules (e.g. ``calendar`` on Python 3.12+).
 * FIX: Fixed ``@contextlib.contextmanager`` bug where the cleanup code (e.g. restoration of ``sys`` attributes) is not run if exceptions occurred inside the context
-* ENH: Added CLI arguments ``-c`` to ``kernprof`` for (auto-)profiling module/package/inline-script execution instead of that of script files; passing ``'-'`` as the script-file name now also reads from and profiles ``stdin``
+* ENH: Added CLI arguments ``-c`` to ``kernprof`` for (auto-)profiling inline-script execution instead of that of script files; passing ``'-'`` as the script-file name now also reads from and profiles ``stdin``
+* ENH: ``kernprof --prof-mod`` target entities are now imported and profiled regardless of whether they are directly imported in the run script/module/code (old behavior recoed by passing ``--no-preimports``); made on-import profiling more aggressive so that it doesn't miss entities like class methods and properties
 
 4.2.0
 ~~~~~

line_profiler/__init__.py

@@ -33,11 +33,13 @@
     pip install line_profiler[all]
 
 
+.. _line-profiler-basic-usage:
+
 Line Profiler Basic Usage
 =========================
 
 To demonstrate line profiling, we first need to generate a Python script to
-profile. Write the following code to a file called ``demo_primes.py``.
+profile. Write the following code to a file called :file:`demo_primes.py`:
 
 .. code:: python
 
@@ -80,8 +82,10 @@ def main():
         main()
 
 
-In this script we explicitly import the ``profile`` function from
-``line_profiler``, and then we decorate function of interest with ``@profile``.
+In this script we explicitly import the
+:py:deco:`profile <line_profiler.explicit_profiler.GlobalProfiler>` function
+from :py:mod:`line_profiler`, and then we decorate function of interest with
+:py:deco:`profile`.
 
 By default nothing is profiled when running the script.
 
@@ -99,17 +103,18 @@ def main():
 
 
 The quickest way to enable profiling is to set the environment variable
-``LINE_PROFILE=1`` and running your script as normal.
-
-.... todo: add a link that points to docs showing all the different ways to enable profiling.
+:envvar:`LINE_PROFILE=1 <LINE_PROFILE>` and running your script as normal.
 
+.. .. todo: add a link that points to docs showing all the different ways to
+.. .. to enable profiling.
 
 .. code:: bash
 
     LINE_PROFILE=1 python demo_primes.py
 
-This will output 3 files: profile_output.txt, profile_output_<timestamp>.txt,
-and profile_output.lprof and stdout will look something like:
+This will output 3 files: :file:`profile_output.txt`,
+:file:`profile_output_<timestamp>.txt`, and :file:`profile_output.lprof`; and
+:file:`stdout` will look something like:
 
 
 .. code::
@@ -219,7 +224,7 @@ def main():
 
 * `timeit <https://docs.python.org/3/library/timeit.html>`_: The builtin timeit module for profiling single statements.
 
-* `timerit <https://github.com/Erotemic/timerit>`_: A multi-statements alternative to the builtin ``timeit`` module.
+* `timerit <https://github.com/Erotemic/timerit>`_: A multi-statements alternative to the builtin :py:mod:`timeit` module.
 
 * `torch.profiler <https://pytorch.org/docs/stable/profiler.html>`_ tools for profiling torch code.