Add manual examples page to docs

pyutils · Oct 5, 2024 · 65bda1d · 65bda1d
1 parent d091d4e
commit 65bda1d
Show file tree

Hide file tree

Showing 3 changed files with 67 additions and 5 deletions.
diff --git a/docs/source/index.rst b/docs/source/index.rst
@@ -11,6 +11,8 @@
    auto/line_profiler.explicit_profiler
    auto/kernprof
 
+   manual/examples/index
+
 
 Indices and tables
 ==================

diff --git a/docs/source/manual/examples/example_units.rst b/docs/source/manual/examples/example_units.rst
@@ -1,5 +1,8 @@
-How to change units
--------------------
+Timing Units
+------------
+
+This example demonstrates how you can change the units in which the time is
+reported.
 
 .. code:: bash
 
@@ -16,7 +19,6 @@ How to change units
             return True
 
 
-        @profile
         def find_primes(size):
             primes = []
             for n in range(size):
@@ -26,7 +28,6 @@ How to change units
             return primes
 
 
-        @profile
         def main():
             print('start calculating')
             primes = find_primes(10)
@@ -44,6 +45,65 @@ How to change units
 
    # Use different values for the unit report
    python -m line_profiler -rtmz --unit 1 profile_output.lprof
+   python -m line_profiler -rtmz --unit 1e-3 profile_output.lprof
    python -m line_profiler -rtmz --unit 1e-6 profile_output.lprof
    python -m line_profiler -rtmz --unit 1e-9 profile_output.lprof
 
+
+You will notice the relevant difference in the output lines:
+
+
+.. code::
+
+
+    ==============
+    unit 1 variant
+    ==============
+
+    Timer unit: 1 s
+
+         ...
+
+         6    101010          0.0      0.0      3.6              max_val = n ** 0.5
+         7    101010          0.1      0.0      4.0              stop = int(max_val + 1)
+
+         ...
+
+    =================
+    unit 1e-3 variant
+    =================
+
+    Timer unit: 0.001 s
+
+         ...
+
+         6    101010         46.6      0.0      3.6              max_val = n ** 0.5
+         7    101010         51.5      0.0      4.0              stop = int(max_val + 1)
+
+         ...
+
+    =================
+    unit 1e-6 variant
+    =================
+
+    Timer unit: 1e-06 s
+
+         ...
+
+         6    101010      46558.2      0.5      3.6              max_val = n ** 0.5
+         7    101010      51491.7      0.5      4.0              stop = int(max_val + 1)
+
+         ...
+
+    =================
+    unit 1e-9 variant
+    =================
+
+    Timer unit: 1e-09 s
+
+         ...
+
+         6    101010   46558246.0    460.9      3.6              max_val = n ** 0.5
+         7    101010   51491716.0    509.8      4.0              stop = int(max_val + 1)
+
+         ...
diff --git a/line_profiler/__init__.py b/line_profiler/__init__.py
@@ -224,7 +224,7 @@ def main():
 * `torch.profiler <https://pytorch.org/docs/stable/profiler.html>`_ tools for profiling torch code.
 
 
-.... todo: give more details on exact limitations.
+.. .. todo: give more details on exact limitations.
 
 """
 # Note: there are better ways to generate primes