Doc updates

kernprof.py
    - Fixed broken link to `@line_profiler.profile` (or
      `line_profiler.explicit_profiler.GlobalProfiler`)
    - Suppressed link for the `-v` flag which linked to some nonsense

line_profiler/__init__.py
    - Added anchor to section `Line Profiler Basic Usage`
    - Replaced inlines with the appropriate roles
    - Fixed broken link to `@line_profiler.profile`
    - Fixed accidentally uncommented TODO

Author: TTsangSC

kernprof.py

@@ -4,7 +4,7 @@
 circumstances.
 
 To profile a script, decorate the functions of interest with
-:py:deco:`profile`:
+:py:deco:`profile <line_profiler.explicit_profiler.GlobalProfiler>`:
 
 .. code:: bash
 
@@ -19,25 +19,27 @@ def main():
 
     New in 4.1.0: Instead of relying on injecting :py:deco:`profile`
     into the builtins you can now ``import line_profiler`` and use
-    :py:deco:`line_profiler.profile` to decorate your functions. This
-    allows the script to remain functional even if it is not actively
-    profiled. See :py:mod:`line_profiler` for details.
+    :py:deco:`line_profiler.profile <line_profiler.explicit_profiler.GlobalProfiler>`
+    to decorate your functions.  This allows the script to remain
+    functional even if it is not actively profiled.  See
+    :py:mod:`!line_profiler` (:ref:`link <line-profiler-basic-usage>`) for
+    details.
 
 
-Then run the script using :command:`kernprof`:
+Then run the script using :program:`kernprof`:
 
 .. code:: bash
 
     kernprof -b script_to_profile.py
 
 By default this runs with the default :py:mod:`cProfile` profiler and
 does not require compiled modules. Instructions to view the results will
-be given in the output. Alternatively, adding :option:`-v` to the
+be given in the output. Alternatively, adding :option:`!-v` to the
 command line will write results to stdout.
 
 To enable line-by-line profiling, :py:mod:`line_profiler` must be
-available and compiled, and the :option:`-l` argument should be added to
-the :command:`kernprof` invocation:
+available and compiled, and the :option:`!-l` argument should be added to
+the :program:`kernprof` invocation:
 
 .. code:: bash
 
@@ -49,19 +51,19 @@ def main():
 
     * :command:`kernprof <options> -m some.module <args to module>`
       parallels :command:`python -m` and runs the provided module as
-      ``__main__``.
+      :py:mod:`__main__`.
     * :command:`kernprof <options> -c "some code" <args to code>`
       parallels :command:`python -c` and executes the provided literal
       code.
     * :command:`kernprof <options> - <args to code>` parallels
       :command:`python -` and executes literal code passed via the
-      ``stdin``.
+      :file:`stdin`.
 
     See also
     :doc:`kernprof invocations </manual/examples/example_kernprof>`.
 
 For more details and options, refer to the CLI help.
-To view :command:`kernprof` help run:
+To view the :program:`kernprof` help text run:
 
 .. code:: bash
 
@@ -106,12 +108,12 @@ def main():
 NOTE:
 
     New in 4.3.0: For more intuitive profiling behavior, profiling
-    targets in :option:`--prof-mod` (except the profiled script/code)
+    targets in :option:`!--prof-mod` (except the profiled script/code)
     are now eagerly pre-imported to be profiled
     (see :py:mod:`line_profiler.autoprofile.eager_preimports`),
     regardless of whether those imports directly occur in the profiled
     script/module/code.
-    To restore the old behavior, pass the :option:`--no-preimports`
+    To restore the old behavior, pass the :option:`!--no-preimports`
     flag.
 """
 import builtins
@@ -265,7 +267,7 @@ def _python_command():
 
 def _normalize_profiling_targets(targets):
     """
-    Normalize the parsed :option:`--prof-mod` by:
+    Normalize the parsed :option:`!--prof-mod` by:
 
     * Normalizing file paths with :py:func:`find_script()`, and
       subsequently to absolute paths.
@@ -338,7 +340,7 @@ def wrapper(*args, **kwargs):
 def pre_parse_single_arg_directive(args, flag, sep='--'):
     """
     Pre-parse high-priority single-argument directives like
-    :option:`-m module` to emulate the behavior of
+    :option:`!-m module` to emulate the behavior of
     :command:`python [...]`.
 
     Examples

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.