[docs] Add missing references in module docs.

Make some deprecated types hidden from generated docs.

docs/api.rst

@@ -3,17 +3,23 @@
 ``scenedetect`` 🎬 Package
 ***********************************************************************
 
-The `scenedetect` API is easy to integrate with most application workflows, while also being highly extensible. See the `Quickstart`_ and `Example`_ sections below for some common use cases and integrations. The `scenedetect` package contains several modules:
+The `scenedetect` API is easy to integrate with most application workflows, while also being highly extensible. See the `Getting Started`_ section below for some common use cases and integrations. The `scenedetect` package contains several modules:
+
+ * :ref:`scenedetect 🎬 <scenedetect-functions>`: Includes the :func:`scenedetect.detect <scenedetect.detect>` function which takes a path and a :ref:`detector <scenedetect-detectors>` to find scene transitions (:ref:`example <scenedetect-quickstart>`), and :func:`scenedetect.open_video <scenedetect.open_video>` for video input
 
  * :ref:`scenedetect.scene_manager 🎞️ <scenedetect-scene_manager>`: The :class:`SceneManager <scenedetect.scene_manager.SceneManager>` acts as a way to coordinate detecting scenes (via `SceneDetector` instances) on video frames (via :ref:`VideoStream <scenedetect-video_stream>` instances). This module also contains functionality to export information about scenes in various formats: :func:`save_images <scenedetect.scene_manager.save_images>` to save images for each scene, :func:`write_scene_list <scenedetect.scene_manager.write_scene_list>` to save scene/cut info as CSV, and :func:`write_scene_list_html <scenedetect.scene_manager.write_scene_list_html>` to export scenes in viewable HTML format.
 
  * :ref:`scenedetect.detectors 🕵️ <scenedetect-detectors>`: Detection algorithms:
 
- * :mod:`ContentDetector <scenedetect.detectors.content_detector>`: detects fast changes/cuts in video content.
+ * :mod:`ContentDetector <scenedetect.detectors.content_detector>`: detects fast cuts using weighted average of HSV changes
+
+ * :mod:`ThresholdDetector <scenedetect.detectors.threshold_detector>`: finds fades in/out using average pixel intensity changes in RGB
+
+ * :mod:`AdaptiveDetector <scenedetect.detectors.adaptive_detector>` finds fast cuts using rolling average of HSL changes
 
- * :mod:`ThresholdDetector <scenedetect.detectors.threshold_detector>`: detects changes in video brightness/intensity.
+ * :mod:`HistogramDetector <scenedetect.detectors.histogram_detector>` finds fast cuts using HSV histogram changes
 
- * :mod:`AdaptiveDetector <scenedetect.detectors.adaptive_detector>`: similar to `ContentDetector` but may result in less false negatives during rapid camera movement.
+ * :mod:`HashDetector <scenedetect.detectors.hash_detector>`: finds fast cuts using perceptual image hashing
 
  * :ref:`scenedetect.video_stream 🎥 <scenedetect-video_stream>`: Video input is handled through the :class:`VideoStream <scenedetect.video_stream.VideoStream>` interface. Implementations for common video libraries are provided in :mod:`scenedetect.backends`:
 
@@ -30,7 +36,7 @@ The `scenedetect` API is easy to integrate with most application workflows, whil
 
  * :ref:`scenedetect.scene_detector 🌐 <scenedetect-scene_detector>`: Contains :class:`SceneDetector <scenedetect.scene_detector.SceneDetector>` interface which detection algorithms must implement.
 
- * :ref:`scenedetect.stats_manager 🧮 <scenedetect-stats_manager>`: Contains :class:`StatsManager <scenedetect.stats_manager.StatsManager>` class for caching frame metrics and loading/saving them to disk in CSV format for analysis. Also used as a persistent cache to make multiple passes on the same video significantly faster.
+ * :ref:`scenedetect.stats_manager 🧮 <scenedetect-stats_manager>`: Contains :class:`StatsManager <scenedetect.stats_manager.StatsManager>` class for caching frame metrics and loading/saving them to disk in CSV format for analysis.
 
  * :ref:`scenedetect.platform 🐱‍💻 <scenedetect-platform>`: Logging and utility functions.
 
@@ -49,38 +55,33 @@ Most types/functions are also available directly from the `scenedetect` package
 .. _scenedetect-quickstart:
 
 =======================================================================
-Examples
+Getting Started
 =======================================================================
 
-To get started, the :func:`scenedetect.detect` function takes a path to a video and a :ref:`scene detector object<scenedetect-detectors>`, and returns a list of start/end timecodes. For detecting fast cuts (shot changes), we use the :class:`ContentDetector <scenedetect.detectors.content_detector.ContentDetector>`:
+PySceneDetect makes it very easy to find scene transitions in a video with the :func:`scenedetect.detect` function:
 
 .. code:: python
 
  from scenedetect import detect, ContentDetector
- scene_list = detect("my_video.mp4", ContentDetector())
+ path = "video.mp4"
+ scenes = detect(path, ContentDetector())
+ for (scene_start, scene_end) in scenes:
+ print(f'{scene_start}-{scene_end}')
 
-``scene_list`` is now a list of :class:`FrameTimecode <scenedetect.frame_timecode.FrameTimecode>` pairs representing the start/end of each scene (try calling ``print(scene_list)``). Note that you can set ``show_progress=True`` when calling :func:`detect <scenedetect.detect>` to display a progress bar with estimated time remaining.
+``scenes`` now contains a list of :class:`FrameTimecode <scenedetect.frame_timecode.FrameTimecode>` pairs representing the start/end of each scene. Note that you can set ``show_progress=True`` when calling :func:`detect <scenedetect.detect>` to display a progress bar with estimated time remaining.
 
-Next, let's print the scene list in a more readable format by iterating over it:
-
-.. code:: python
-
- for i, scene in enumerate(scene_list):
- print("Scene %2d: Start %s / Frame %d, End %s / Frame %d" % (
- i+1,
- scene[0].get_timecode(), scene[0].get_frames(),
- scene[1].get_timecode(), scene[1].get_frames(),))
-
-Now that we know where each scene is, we can also :ref:`split the input video <scenedetect-video_splitter>` automatically using `ffmpeg` (`mkvmerge` is also supported):
+Here, we use :mod:`ContentDetector <scenedetect.detectors.content_detector>` to detect fast cuts. There are :ref:`many detector types <scenedetect-detectors>` which can be used to find fast cuts and fades in/out. PySceneDetect can also export scene data in various formats, and can :ref:`split the input video <scenedetect-video_splitter>` automatically if `ffmpeg` is available:
 
 .. code:: python
 
  from scenedetect import detect, ContentDetector, split_video_ffmpeg
  scene_list = detect("my_video.mp4", ContentDetector())
- split_video_ffmpeg("my_video.mp4", scene_list)
+ split_video_ffmpeg("my_video.mp4", scenes)
 
 Recipes for common use cases can be `found on Github <https://github.com/Breakthrough/PySceneDetect/blob/v0.6.4-release/tests/test_api.py>`_ including limiting detection time and storing per-frame metrics. For advanced workflows, start with the :ref:`SceneManager usage examples <scenedetect-scene_manager>`.
 
+.. _scenedetect-functions:
+
 =======================================================================
 Functions
 =======================================================================
@@ -106,6 +107,7 @@ Module Reference
  api/scene_detector
  api/video_stream
  api/platform
+ api/migration_guide
 
 
 =======================================================================

docs/api/migration_guide.rst

@@ -5,7 +5,7 @@
 Migration Guide
 ---------------------------------------------------------------
 
-This page details how to transition a program written using PySceneDetect 0.5 to the new 0.6 API. It is recommended to review the new :ref:`Example <scenedetect-example>` section first, as it covers the majority of use cases. Also see `tests/test_api.py <https://github.com/Breakthrough/PySceneDetect/blob/v0.6.4-release/tests/test_api.py>`_ for a set of demonstrations covering many high level use cases.
+This page details how to transition a program written using PySceneDetect 0.5 to the new 0.6 API. It is recommended to review the new :ref:`Example <scenedetect-quickstart>` section first, as it covers the majority of use cases. Also see `tests/test_api.py <https://github.com/Breakthrough/PySceneDetect/blob/v0.6.4-release/tests/test_api.py>`_ for a set of demonstrations covering many high level use cases.
 
 PySceneDetect v0.6 is a major step towards a more stable and simplified API. The biggest change to existing workflows is how video input is handled, and that Python 3.6 or above is now required.
 

docs/index.rst

@@ -54,7 +54,6 @@ Table of Contents
  api/scene_detector
  api/video_stream
  api/platform
- api/migration_guide
 
 =======================================================================
 Indices and Tables

scenedetect/scene_manager.py

@@ -1086,6 +1086,8 @@ def get_cut_list(
  List of FrameTimecode objects denoting the points in time where a scene change
  was detected in the input video, which can also be passed to external tools
  for automated splitting of the input into individual scenes.
+
+ :meta private:
  """
  # TODO(v0.7): Use the warnings module to turn this into a warning.
  if show_warning:
@@ -1108,6 +1110,8 @@ def get_event_list(
 
  Returns:
  List of pairs of FrameTimecode objects denoting the detected scenes.
+
+ :meta private:
  """
  # TODO(v0.7): Use the warnings module to turn this into a warning.
  logger.error("`get_event_list()` is deprecated and will be removed in a future release.")

scenedetect/stats_manager.py

@@ -49,13 +49,19 @@
 
 
 class FrameMetricRegistered(Exception):
- """[DEPRECATED - DO NOT USE] No longer used."""
+ """[DEPRECATED - DO NOT USE] No longer used.
+
+ :meta private:
+ """
 
  pass
 
 
 class FrameMetricNotRegistered(Exception):
- """[DEPRECATED - DO NOT USE] No longer used."""
+ """[DEPRECATED - DO NOT USE] No longer used.
+
+ :meta private:
+ """
 
  pass
 
@@ -236,6 +242,8 @@ def load_from_csv(self, csv_file: Union[str, bytes, TextIO]) -> Optional[int]:
  Raises:
  StatsFileCorrupt: Stats file is corrupt and can't be loaded, or wrong file
  was specified.
+
+ :meta private:
  """
  # TODO: Make this an error, then make load_from_csv() a no-op, and finally, remove it.
  logger.warning("load_from_csv() is deprecated and will be removed in a future release.")

scenedetect/video_splitter.py

@@ -174,7 +174,7 @@ def split_video_mkvmerge(
  is supported by this function.
  video_name (str): Name of the video to be substituted in output_file_template for
  $VIDEO_NAME. If not specified, will be obtained from the filename.
- show_output: If False, adds the --quiet flag when invoking `mkvmerge`..
+ show_output: If False, adds the --quiet flag when invoking `mkvmerge`.
  suppress_output: [DEPRECATED] DO NOT USE. For backwards compatibility only.
  Returns:
  Return code of invoking mkvmerge (0 on success). If scene_list is empty, will