Implement doc tree builder with toml, yaml and custom format

This is to help create fixtures, so I can write meaningfull tests without
too much pain and then refactor this code without having to manually
look at the pages.

Author: pedro-psb

pyproject.toml

@@ -30,3 +30,9 @@ pulp_docs = ["data/**"]
 [tool.setuptools.packages.find]
 where = ["src"]
 
+[tool.pytest.ini_options]
+pythonpath = "src"
+addopts = [
+    "--import-mode=importlib",
+]
+

src/pulp_docs/test_tools/__init__.py

@@ -0,0 +1,72 @@
+from pathlib import Path
+
+import tomllib
+import yaml
+import re
+
+
+def parse_doctree_file(doctree_file: Path, target: Path, project_name: str = "foobar"):
+    """Create a whole documentation tree base on @doctree_file on @target.
+
+    The goal is to facilitate creating fixtures for testing complex build cases, such
+    as pulp structure.
+
+    The declarative doctree file specifies a list of (path,content) tuples, with an semantic
+    header separation..
+
+    The overall structure is:
+
+    ```pseudo-format
+    {
+        projet-name-1: [{path: content}, ...,  {path: content}],
+        ...
+        projet-name-N: [{path: content}, ..., {path: content}],
+    }
+    ```
+
+    See `test_doctree_writer` for samples.
+
+    Params:
+        doctree_file: The file with a supported extenstion format. E.g: `.toml` `.yml` and `.doctree`
+        target: The directory where the project should be writter to.
+    """
+
+    def custom_parser(file: Path):
+        _data = file.read_text()
+        section_match = r"\n*\[\[\s*[\w-]+\s*\]\]\n"
+        item_match = r"----+\n"
+        section_split = [
+            section for section in re.split(section_match, _data) if section
+        ]
+        item_split = [
+            item
+            for section in section_split
+            for item in re.split(item_match, section)
+            if section and item
+        ]
+        item_partition = [t.partition("\n\n") for t in item_split if t]
+
+        def sanitize_path(s):
+            return s.partition("\n")[0].strip(" ")
+
+        items = [{"path": sanitize_path(s[0]), "data": s[2]} for s in item_partition]
+        return {"foobar": items}
+
+    # Open and parse doctree file
+    if doctree_file.suffix in (".yml", ".yaml"):
+        data = yaml.load(doctree_file.read_text(), Loader=yaml.SafeLoader)
+    elif doctree_file.suffix in (".toml",):
+        data = tomllib.loads(doctree_file.read_text())
+    elif doctree_file.suffix in (".doctree",):
+        data = custom_parser(doctree_file)
+        # breakpoint()
+    else:
+        raise NotImplementedError(f"File type not supported: {doctree_file.name}")
+
+    # Create all directories
+    for prj_name, contents in data.items():
+        for item in contents:
+            basedir, _, filename = item["path"].strip("/").rpartition("/")
+            basedir = target / basedir
+            basedir.mkdir(parents=True, exist_ok=True)
+            Path(target / basedir / filename).write_text(item["data"])

src/pulp_docs/test_tools/doctree_writer.py

@@ -0,0 +1,101 @@
+from pathlib import Path
+
+import pytest
+import textwrap
+
+from pulp_docs.test_tools.doctree_writer import parse_doctree_file
+
+file_sample = """\
+# check-title
+
+check-content
+
+---
+not/a/path (separator must have 4+ ---)
+
+dont split."""
+
+yaml_sample = f"""\
+project1:
+  - path: docs/index.md
+    data: |
+{textwrap.indent(file_sample, " " * 6)}
+  - path: docs/guides/foo.md
+    data: |
+{textwrap.indent(file_sample, " " * 6)}
+project2:
+  - path: docs/guides/bar.md
+    data: |
+{textwrap.indent(file_sample, " " * 6)}
+"""
+
+toml_sample = f"""\
+[[project1]]
+path = 'docs/index.md'
+data = '''
+{file_sample}
+'''
+
+[[project1]]
+path = 'docs/guides/foo.md'
+data = '''
+{file_sample}
+'''
+
+[[project2]]
+path = 'docs/guides/bar.md'
+data = '''
+{file_sample}
+'''
+"""
+
+# .doctree extenstion
+custom_sample = f"""\
+[[ project1 ]]
+------------------------
+docs/index.md
+
+{file_sample}
+-----------------
+docs/guides/foo.md
+---------------#ignore
+
+{file_sample}
+
+[[ project2 ]]
+-----
+docs/guides/bar.md
+
+{file_sample}
+"""
+
+
+@pytest.mark.parametrize(
+    "file_ext,content",
+    [
+        pytest.param("toml", toml_sample, id="toml"),
+        pytest.param("yaml", yaml_sample, id="yaml"),
+        pytest.param("yml", yaml_sample, id="yml"),
+        pytest.param("doctree", custom_sample, id="doctree"),
+    ],
+)
+def test_doctree_write(file_ext, content, tmp_path):
+    sample_file = tmp_path / f"declarative_fixture.{file_ext}"
+    sample_file.write_text(content)
+    parse_doctree_file(sample_file, tmp_path)
+
+    pages = ("docs/index.md", "docs/guides/foo.md", "docs/guides/bar.md")
+    for page_path in pages:
+        assert Path(tmp_path / page_path).exists()
+
+    contents = []
+    for page_path in pages:
+        content = Path(tmp_path / page_path).read_text()
+        contents.append(content)
+        assert "# check-title" in content
+        assert "check-content" in content
+        assert "[[ project1 ]]" not in content
+        assert "[[ project2 ]]" not in content
+
+    print()
+    print(f"To check manually cd to:\n{tmp_path}")