Update docs

README.rst

@@ -78,6 +78,43 @@ To apply glob patterns on the file paths, the ``--glob`` option can be used.
 To selection only *mscz* oder *mscx* files use the options ``--mscz`` or ``--mscx``.
 Don’t mix the options ``--mscz`` and ``--mscx`` with the option ``--glob``.
 
+The python package ``mscxyz`` exports a function named ``list_files`` which can
+be used to list the paths of MuseScore files. This allows you to list score
+paths in a nested folder structure in a similar way to the command line.
+This folder structure is used for the following example:
+
+::
+
+    cd /home/xyz/scores
+    find . | sort
+
+    .
+    ./level1
+    ./level1/level2
+    ./level1/level2/score2.mscz
+    ./level1/level2/level3
+    ./level1/level2/level3/score3.mscz
+    ./level1/score1.mscz
+    ./score0.mscz
+
+.. code-block:: Python
+
+    from mscxyz import list_files, Score
+
+    score_paths = []
+    for score_path in list_files(path="/home/xyz/scores", extension="mscz"):
+        score = Score(score_path)
+        assert score.path.exists()
+        assert score.extension == "mscz"
+        score_paths.append(str(score_path))
+
+    assert len(score_paths) == 4
+
+    assert "level1/level2/level3/score3.mscz" in score_paths[3]
+    assert "level1/level2/score2.mscz" in score_paths[2]
+    assert "level1/score1.mscz" in score_paths[1]
+    assert "score0.mscz" in score_paths[0]
+
 ... export files to different files types?
 ------------------------------------------
 
@@ -773,41 +810,6 @@ The output of the code example is very long, so here is a shortened version:
         <metaTag>
         ...
 
-List score paths in a nested folder structure:
-
-::
-
-    cd /home/xyz/scores
-    find . | sort
-
-::
-
-    .
-    ./level1
-    ./level1/level2
-    ./level1/level2/score2.mscz
-    ./level1/level2/level3
-    ./level1/level2/level3/score3.mscz
-    ./level1/score1.mscz
-    ./score0.mscz
-
-.. code-block:: Python
-
-    from mscxyz import list_score_paths, Score
-
-    score_paths = list_score_paths(path="/home/xyz/scores", extension="mscz")
-    for score_path in score_paths:
-        score = Score(score_path)
-        assert score.path.exists()
-        assert score.extension == "mscz"
-
-    assert len(score_paths) == 4
-
-    assert "level1/level2/level3/score3.mscz" in score_paths[0]
-    assert "level1/level2/score2.mscz" in score_paths[1]
-    assert "level1/score1.mscz" in score_paths[2]
-    assert "score0.mscz" in score_paths[3]
-
 ``meta``
 --------
 

README_template.rst

@@ -71,10 +71,46 @@ To apply glob patterns on the file paths, the ``--glob`` option can be used.
 
     musescore-manager -L --glob "*/folder/*.mscz"
 
-
 To selection only *mscz* oder *mscx* files use the options ``--mscz`` or ``--mscx``.
 Don’t mix the options ``--mscz`` and ``--mscx`` with the option ``--glob``.
 
+The python package ``mscxyz`` exports a function named ``list_files`` which can
+be used to list the paths of MuseScore files. This allows you to list score
+paths in a nested folder structure in a similar way to the command line.
+This folder structure is used for the following example:
+
+::
+
+    cd /home/xyz/scores
+    find . | sort
+
+    .
+    ./level1
+    ./level1/level2
+    ./level1/level2/score2.mscz
+    ./level1/level2/level3
+    ./level1/level2/level3/score3.mscz
+    ./level1/score1.mscz
+    ./score0.mscz
+
+.. code-block:: Python
+
+    from mscxyz import list_files, Score
+
+    score_paths = []
+    for score_path in list_files(path="/home/xyz/scores", extension="mscz"):
+        score = Score(score_path)
+        assert score.path.exists()
+        assert score.extension == "mscz"
+        score_paths.append(str(score_path))
+
+    assert len(score_paths) == 4
+
+    assert "level1/level2/level3/score3.mscz" in score_paths[3]
+    assert "level1/level2/score2.mscz" in score_paths[2]
+    assert "level1/score1.mscz" in score_paths[1]
+    assert "score0.mscz" in score_paths[0]
+
 ... export files to different files types?
 ------------------------------------------
 
@@ -327,42 +363,6 @@ The output of the code example is very long, so here is a shortened version:
         <metaTag>
         ...
 
-
-List score paths in a nested folder structure:
-
-::
-
-    cd /home/xyz/scores
-    find . | sort
-
-::
-
-    .
-    ./level1
-    ./level1/level2
-    ./level1/level2/score2.mscz
-    ./level1/level2/level3
-    ./level1/level2/level3/score3.mscz
-    ./level1/score1.mscz
-    ./score0.mscz
-
-.. code-block:: Python
-
-    from mscxyz import list_score_paths, Score
-
-    score_paths = list_score_paths(path="/home/xyz/scores", extension="mscz")
-    for score_path in score_paths:
-        score = Score(score_path)
-        assert score.path.exists()
-        assert score.extension == "mscz"
-
-    assert len(score_paths) == 4
-
-    assert "level1/level2/level3/score3.mscz" in score_paths[0]
-    assert "level1/level2/score2.mscz" in score_paths[1]
-    assert "level1/score1.mscz" in score_paths[2]
-    assert "score0.mscz" in score_paths[3]
-
 ``meta``
 --------
 

docs/conf.py

@@ -9,6 +9,7 @@
 
 extensions: list[str] = [
     "sphinx.ext.autodoc",
+    "sphinx.ext.autosummary",
     "sphinx.ext.viewcode",
 ]
 templates_path: list[str] = ["_templates"]

docs/main-module.rst

@@ -1,4 +1,12 @@
 Main module
 -----------
 
+
+.. autosummary::
+   :toctree: stubs
+   :nosignatures:
+
+   mscxyz.list_files
+   mscxyz.Score
+
 .. automodule:: mscxyz

docs/other-submodules.rst

@@ -20,3 +20,4 @@ mscxyz.utils module
 ^^^^^^^^^^^^^^^^^^^
 
 .. automodule:: mscxyz.utils
+    :noindex:

docs/stubs/mscxyz.Score.rst

@@ -0,0 +1,56 @@
+mscxyz.Score
+============
+
+.. currentmodule:: mscxyz
+
+.. autoclass:: Score
+
+
+   .. automethod:: __init__
+
+
+   .. rubric:: Methods
+
+   .. autosummary::
+
+      ~Score.__init__
+      ~Score.backup
+      ~Score.change_path
+      ~Score.get_version
+      ~Score.make_snapshot
+      ~Score.new
+      ~Score.print_diff
+      ~Score.read_as_text
+      ~Score.reload
+      ~Score.save
+
+
+
+
+
+   .. rubric:: Attributes
+
+   .. autosummary::
+
+      ~Score.backup_file
+      ~Score.basename
+      ~Score.dirname
+      ~Score.export
+      ~Score.extension
+      ~Score.fields
+      ~Score.filename
+      ~Score.json_file
+      ~Score.lyrics
+      ~Score.meta
+      ~Score.style
+      ~Score.style_file
+      ~Score.version_major
+      ~Score.xml_string
+      ~Score.zip_container
+      ~Score.path
+      ~Score.xml_file
+      ~Score.xml_root
+      ~Score.xml
+      ~Score.version
+
+

docs/stubs/mscxyz.list_files.rst

@@ -0,0 +1,6 @@
+mscxyz.list\_files
+==================
+
+.. currentmodule:: mscxyz
+
+.. autofunction:: list_files

docs/submodule-score.rst

@@ -2,3 +2,4 @@ Submodule ``score``
 ^^^^^^^^^^^^^^^^^^^
 
 .. automodule:: mscxyz.score
+   :noindex:

mscxyz/__init__.py

@@ -19,11 +19,4 @@
 
 Score = mscxyz.score.Score
 
-Lyrics = mscxyz.lyrics.Lyrics
-
-Meta = mscxyz.meta.Meta
-
-Style = mscxyz.style.Style
-
 list_files = utils.list_files
-"""list_score_paths"""

tests/test_api.py

@@ -3,10 +3,7 @@
 
 
 from mscxyz import (
-    Lyrics,
-    Meta,
     Score,
-    Style,
     list_files,
 )
 
@@ -15,17 +12,5 @@ def test_class_score() -> None:
     assert Score.__name__ == "Score"
 
 
-def test_class_lyrics() -> None:
-    assert Lyrics.__name__ == "Lyrics"
-
-
-def test_class_meta() -> None:
-    assert Meta.__name__ == "Meta"
-
-
-def test_class_style() -> None:
-    assert Style.__name__ == "Style"
-
-
 def test_function_list_scores() -> None:
     assert list_files.__name__ == "list_files"

tests/test_examples.py

@@ -31,20 +31,20 @@ def print_elements(element: _Element, level: int) -> None:
     print_elements(score.xml_root, 0)
 
 
-def test_list_score_paths(nested_dir: Path) -> None:
-    score_paths = list(list_files(src=str(nested_dir), extension="mscz"))
-    for score_path in score_paths:
+def test_list_files(nested_dir: Path) -> None:
+    score_paths: list[str] = []
+    for score_path in list_files(src=str(nested_dir), extension="mscz"):
         score = Score(score_path)
         assert score.path.exists()
         assert score.extension == "mscz"
+        score_paths.append(str(score_path))
 
     assert len(score_paths) == 4
 
-    score_paths.sort()
-    assert "score0.mscz" in str(score_paths[3])
-    assert "level1/score1.mscz" in str(score_paths[2])
-    assert "level1/level2/score2.mscz" in str(score_paths[1])
-    assert "level1/level2/level3/score3.mscz" in str(score_paths[0])
+    assert "level1/level2/level3/score3.mscz" in score_paths[3]
+    assert "level1/level2/score2.mscz" in score_paths[2]
+    assert "level1/score1.mscz" in score_paths[1]
+    assert "score0.mscz" in score_paths[0]
 
 
 @pytest.mark.skip("Will be fixed later")