Streamline README and move long usage notes into docs

docs/source/auto/line_profiler.rst

@@ -28,7 +28,6 @@ Submodules
 Module contents
 ---------------
 
-.. automodule:: line_profiler
-   :members:
-   :undoc-members:
-   :show-inheritance:
+The package overview and top-level usage documentation are rendered on the
+main documentation page. This page keeps the generated subpackage and submodule
+navigation in one place.

docs/source/auto/line_profiler.toml_config.rst

@@ -1,5 +1,5 @@
 line\_profiler.toml\_config module
-================================
+======================================
 
 .. automodule:: line_profiler.toml_config
    :members:

docs/source/conf.py

@@ -274,7 +274,10 @@ def visit_Assign(self, node):
 # The suffix(es) of source filenames.
 # You can specify multiple suffix as a list of string:
 #
-source_suffix = ['.rst', '.md']
+source_suffix = {
+    '.rst': 'restructuredtext',
+    '.md': 'markdown',
+}
 
 # The master toctree document.
 master_doc = 'index'
@@ -289,7 +292,15 @@ def visit_Assign(self, node):
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
 # This pattern also affects html_static_path and html_extra_path .
-exclude_patterns = []
+exclude_patterns = [
+    # Stale sphinx-apidoc entry points. The canonical API navigation is
+    # rooted at auto/line_profiler.rst and docs/source/index.rst.
+    'modules.rst',
+    'auto/modules.rst',
+    # There is no importable Python module named line_profiler.timers; the
+    # timers implementation lives in C support files.
+    'auto/line_profiler.timers.rst',
+]
 
 # The name of the Pygments (syntax highlighting) style to use.
 pygments_style = 'sphinx'
@@ -301,15 +312,13 @@ def visit_Assign(self, node):
 # a list of builtin themes.
 #
 html_theme = 'sphinx_rtd_theme'
-html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
 
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the
 # documentation.
 #
 html_theme_options = {
     'collapse_navigation': False,
-    'display_version': True,
     'navigation_depth': -1,
     # 'logo_only': True,
 }

docs/source/index.rst

@@ -2,6 +2,12 @@
 .. automodule:: line_profiler.__init__
    :show-inheritance:
 
+.. toctree::
+   :maxdepth: 2
+   :caption: User Guide
+
+   manual/index
+
 .. toctree::
    :maxdepth: 8
    :caption: Package Layout
@@ -11,8 +17,6 @@
    auto/line_profiler.explicit_profiler
    auto/kernprof
 
-   manual/examples/index
-
 
 Indices and tables
 ==================

docs/source/manual/examples/example_kernprof.rst

@@ -262,8 +262,10 @@ like ``python -c``:
       argument thereafter (the executed code).
       If there isn't one, an error is raised as
       :ref:`above <kernprof-m-note>` with ``kernprof -m``.
-    * .. _kernprof-c-note:
-      Since the temporary file containing the executed code will not
+
+    .. _kernprof-c-note:
+
+    * Since the temporary file containing the executed code will not
       exist beyond the ``kernprof`` process, profiling results
       pertaining to targets (function definitions) local to said code
       :ref:`will not be accessible later <kernprof-script-note>` by

docs/source/manual/examples/example_units.rst

@@ -48,6 +48,7 @@ reported use the ``--unit`` command line argument. The following example shows
 4 variants:
 
 .. code:: bash
+
    LINE_PROFILE=1 python script.py
 
    # Use different values for the unit report

docs/source/manual/examples/index.rst

@@ -3,14 +3,17 @@ Examples
 
 Examples of line profiler usage:
 
-+ `Basic Usage <../../index.html#line-profiler-basic-usage>`_
+.. toctree::
+   :maxdepth: 1
 
-+ `Kernprof Usage <example_kernprof.rst>`_
+   Kernprof Usage <example_kernprof>
+   Timing Units <example_units>
+   TOML Config Usage <example_toml_config>
 
-+ `Auto Profiling <../../auto/line_profiler.autoprofile.html#auto-profiling>`_
+Additional API-focused examples:
 
-+ `Explicit Profiler <../../auto/line_profiler.explicit_profiler.html#module-line_profiler.explicit_profiler>`_
++ `Basic Usage <../../index.html#line-profiler-basic-usage>`_
 
-+ `Timing Units <example_units.rst>`_
++ `Auto Profiling <../../auto/line_profiler.autoprofile.html#auto-profiling>`_
 
-+ `TOML Config Usage <example_toml_config.rst>`_
++ `Explicit Profiler <../../auto/line_profiler.explicit_profiler.html#module-line_profiler.explicit_profiler>`_

docs/source/manual/index.rst

@@ -0,0 +1,11 @@
+User Manual
+===========
+
+Longer usage notes, examples, and FAQ entries live here so the top-level
+README can stay short.
+
+.. toctree::
+   :maxdepth: 2
+
+   examples/index
+   legacy_readme