Update python script docs

Signed-off-by: Bryce Ferenczi <[email protected]>

docs/scripts.rst

@@ -3,65 +3,65 @@
 Scripts
 =======
 
-Various helper scripts are included in the complete source code but not included in the python library, since they mostly deal with the dataset generation, rather than dataloading.
+Various helper scripts are included in the source code but not included in the ``sc2-serializer`` library, as they mostly deal with the dataset generation, rather than dataloading.
 
 find_all_versions
 -----------------
 
-.. autofunction:: find_all_versions.compare_replays_and_game
-
-.. autofunction:: find_all_versions.write_replay_versions
+.. automodule:: find_all_versions
+    :members:
 
 
 gen_info_header
 ---------------
 
-Generates generated_info.hpp
+.. automodule:: gen_info_header
+    :members: main
 
 
 gen_info_yaml
 -------------
 
-Generates game_info.yaml
+.. automodule:: gen_info_yaml
 
 
 inspect_replay
 --------------
 
-.. autofunction:: inspect_replay.inspect
-
-.. autofunction:: inspect_replay.count
+.. automodule:: inspect_replay
+    :members: inspect, count
 
 
 make_partitions
 ---------------
 
-.. autofunction:: make_partitions.main
+.. automodule:: make_partitions
+    :members: main
 
 
 merge_info_yaml
 ---------------
 
-.. autofunction:: merge_info_yaml.main
+.. automodule:: merge_info_yaml
+    :members: main
 
 
 replay_parallel
 ---------------
 
-.. autofunction:: replay_parallel.main
+.. automodule:: replay_parallel
+    :members: main
 
 
 replay_sql
 ----------
 
-.. autofunction:: replay_sql.create
-
-.. autofunction:: replay_sql.create_individual
-
-.. autofunction:: replay_sql.merge
+.. automodule:: replay_sql
+    :members: create, create_individual, merge
 
 
 review_resources
 ----------------
 
-.. autofunction:: review_resources.main
+.. automodule:: review_resources
+    :members: main

scripts/find_all_versions.py

@@ -1,3 +1,7 @@
+#!/usr/bin/env python3
+"""Utilities to gather information about SC2
+versions in replays and installed game."""
+
 from pathlib import Path
 from typing import Annotated
 
@@ -8,7 +12,7 @@
 app = typer.Typer()
 
 
-def get_versions_in_tree(root: Path):
+def _get_versions_in_tree(root: Path):
     """
     Recursively query all the sc2 replays in a directory and return a set of all versions present
     Also returns a mapping from unique versions to a replay with that version.
@@ -34,13 +38,14 @@ def get_versions_in_tree(root: Path):
 
 @app.command()
 def compare_replays_and_game(
-    replays: Annotated[Path, typer.Option()], game: Annotated[Path, typer.Option()]
+    replays: Annotated[Path, typer.Option(help="Path to SC2 Replays")],
+    game: Annotated[Path, typer.Option(help="Path to 'Versions' folder of SC2")],
 ):
     """Compare versions of replays with versions of the game verision currently present"""
     assert game.name == "Versions", f"Should point to the Versions folder, got {game}"
     current_bases = {folder.name[len("base") :] for folder in game.glob("Base*")}
     print("Game Build Versions: \n", current_bases)
-    version_file_map = get_versions_in_tree(replays)
+    version_file_map = _get_versions_in_tree(replays)
 
     missing_versions = {
         k: v for k, v in version_file_map.items() if k[2] not in current_bases
@@ -63,12 +68,12 @@ def sort_key(x: tuple[str]):
 
 @app.command()
 def write_replay_versions(
-    replays: Annotated[Path, typer.Option()],
-    output: Annotated[Path, typer.Option()],
+    replays: Annotated[Path, typer.Option(help="Path to SC2 Replays")],
+    output: Annotated[Path, typer.Option(help="Output .csv to write results")],
 ):
     """Write all the game,data,build versions found in folder of replays to a csv"""
     assert output.suffix == ".csv", f"Output should be a .csv file, got {output.suffix}"
-    version_file_map = get_versions_in_tree(replays)
+    version_file_map = _get_versions_in_tree(replays)
 
     with open(output, "w", encoding="utf-8") as out:
         out.write("game,data,build\n")

scripts/gen_info_header.py

@@ -1,12 +1,14 @@
 #!/usr/bin/env python3
 """
-Use PySC2 to generate required C++ Data
+Use PySC2 to generate required C++ header ``generated_info.hpp``.
 
 For generating the default resource quantities, for minearals it
 should be 1800 or 900 depending on if "750" is in the name, as
 the default was changed to these two values since Legacy of the Void
-Vespene is always 2250 since patch 4.0
+Vespene is always 2250 since patch 4.0.
+
 https://starcraft.fandom.com/wiki/Vespene_gas
+
 https://starcraft.fandom.com/wiki/Minerals
 """
 from pathlib import Path
@@ -92,7 +94,7 @@ def add_research_remapping(content: str):
 
 
 @app.command()
-def main(out_folder: Path = Path.cwd()):
+def main(out_folder: Path = Path(".")):
     """Generate C++ Game Info Header based on values from PySC2"""
     content = r"""// ---- Generated by scripts/gen_info_header.py ----
 #pragma once

scripts/gen_info_yaml.py

@@ -1,20 +1,23 @@
 #!/usr/bin/env python3
 """
 Use PySC2 and run over each game version in a folder and write out
-information about different upgrades.
+information about different upgrades. This is the ``game_info.yaml``.
 
 PySC2 doesn't recognise properly that a Version object is passed to it,
 and falsely rejects good version requests, hence a small change in
 pysc2.run_configs.lib.RunConfig where the init checks if version is an
 instance of Version as shown below.
 
-class RunConfig(object):
-  def __init__(self, ......)
-    ....
-    if not isinstance(version, Version):
-      self.version = self._get_version(version)
-    else:
-      self.version = version
+.. code-block:: python
+
+    class RunConfig(object):
+        def __init__(self, ...)
+            ...
+            if not isinstance(version, Version):
+                self.version = self._get_version(version)
+            else:
+                self.version = version
+
 """
 import os
 import platform

scripts/inspect_replay.py

@@ -148,10 +148,7 @@ def inspect(
     file: Annotated[Path, typer.Option(help="SC2Replays file")],
     command: Annotated[SubCommand, typer.Option(help="Thing to run on data")],
     idx: Annotated[int, typer.Option(help="Replay Index")] = 0,
-    outfolder: Annotated[
-        Path, typer.Option(help="Directory to write data")
-    ] = Path.cwd()
-    / "workspace",
+    outfolder: Annotated[Path, typer.Option(help="Results dir")] = Path("."),
 ):
     """Script to poke around and inspect the serialized replay data"""
     db, parser = get_database_and_parser(parse_units=True, parse_minimaps=True)

scripts/make_partitions.py

@@ -1,7 +1,6 @@
 #!/usr/bin/env python3
 """
-Script that creates the partition files
-for running conversions in parallel.
+Script that creates the partition files for running conversions in parallel.
 """
 from dataclasses import dataclass, field
 from pathlib import Path

scripts/replay_parallel.py

@@ -1,3 +1,4 @@
+#!/usr/bin/env python3
 """Convert folders of replays in parallel"""
 
 import concurrent.futures as fut

scripts/replay_sql.py

@@ -1,4 +1,6 @@
 #!/usr/bin/env python3
+"""Utilities to create the metadata sqlite database
+commonly used for filtering poor quality replays"""
 
 import os
 import shutil