Consistent order in auto-generated documentation

Don't depend on how the filesystem reads it; sort to get the same order everywhere.
boxine · Sep 12, 2023 · fe5778a · fe5778a
1 parent f16edc5
commit fe5778a
Show file tree

Hide file tree

Showing 5 changed files with 13 additions and 12 deletions.
diff --git a/bx_py_utils/doc_write/README.md b/bx_py_utils/doc_write/README.md
@@ -66,11 +66,11 @@ Notes:
 
 ### Notes
 
-* All Doc-String without the `{prefix}` will be ignored.
+* The created created Markdown file is relative to `output_base_path` (defined in `pyproject.toml`)
 
-* The `{file-path}` must has the file extension `.md`
-Otherwise the DocString block will be ignored.
+* Headlines will be sorted, so they appears ordered by the level.
 
-* The created created Markdown file is relative to `output_base_path` (defined in `pyproject.toml`)
+* All Doc-String without the `{prefix}` will be ignored.
 
-* Headlines will be sorted, so they appears ordered by the level.
+* The `{file-path}` must has the file extension `.md`
+Otherwise the DocString block will be ignored.
diff --git a/bx_py_utils/doc_write/docstrings.py b/bx_py_utils/doc_write/docstrings.py
@@ -43,7 +43,7 @@ def collect_docstrings(*, config: DocuwriteConfig) -> dict:
     regex = re.compile(config.docstring_prefix + r'\s*(.*?) (#{1,}.+?)\n+(.+)', re.DOTALL)
 
     storage = collections.defaultdict(dict)
-    for file_path in iter_file_path(file_paths=config.search_paths, rglob_pattern='*.py'):
+    for file_path in sorted(iter_file_path(file_paths=config.search_paths, rglob_pattern='*.py')):
         for doc_string in iter_docstrings(file_path=file_path):
             if not doc_string.startswith(config.docstring_prefix):
                 """DocWrite: bx_py_utils/doc_write/README.md ### Notes

diff --git a/bx_py_utils_tests/publish.py b/bx_py_utils_tests/publish.py
@@ -2,8 +2,8 @@
     Helper to publish this Project to PyPi
 """
 
-from pathlib import Path
 import subprocess
+from pathlib import Path
 
 from manageprojects.utilities.publish import publish_package
 

diff --git a/bx_py_utils_tests/tests/test_doc_write_api.py b/bx_py_utils_tests/tests/test_doc_write_api.py
@@ -29,7 +29,7 @@ def test_happy_path(self):
                 inspect.cleandoc(
                     """
                     '''TestDocs: test/README.md # Headline 1
-                    The Doc String 1
+                    The Doc String 2 (from foo)
                     '''
                     """
                 )
@@ -40,7 +40,7 @@ def test_happy_path(self):
                 inspect.cleandoc(
                     """
                     '''TestDocs: test/README.md # Headline 1
-                    Merged Text to Headline 1
+                    Merged Text to Headline 1 (from bar)
                     '''
                     """
                 )
@@ -62,6 +62,7 @@ def test_happy_path(self):
                 DocuwriteConfig(
                     base_path=temp_path,
                     search_paths=[
+                        # intentionally not in alphabetical order
                         temp_path / 'foo',
                         temp_path / 'bar',
                     ],
@@ -81,9 +82,9 @@ def test_happy_path(self):
                     """
                     # Headline 1
 
-                    The Doc String 1
+                    Merged Text to Headline 1 (from bar)
 
-                    Merged Text to Headline 1
+                    The Doc String 2 (from foo)
 
                     ## Headline 2
 

diff --git a/pyproject.toml b/pyproject.toml
@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "bx_py_utils"
-version = "87"
+version = "88"
 description = "Various Python utility functions"
 homepage = "https://github.com/boxine/bx_py_utils/"
 authors = [