"make format" and credits.md - changes affect mkdocs

[gadams999]

Great repo, much less overhead than Hypermodem and cookiecutter.

Getting started with the repo and noticed that if a make format is done, it changes the docs/credits.md file contents which mkdocs then fails. In credits.md there is this (python exec="yes" on the open fence):

--8<-- "scripts/gen_credits.py"

which when make format is run with blacken-docs changes the format to:

--8 < --"scripts/gen_credits.py"

with spaces changes. make check-docs will then error with:

 WARNING -  markdown_exec: Execution of python code block exited with errors

  Code block is:

    --8 < --"scripts/gen_credits.py"

  Output is:

    Traceback (most recent call last):
...

I looked into duty and the lazy callable for blacken_docs has an exclude parameter, but it looks like it's never used. I'll continue to pursue there, but has anyone see this error and was able to correct?

[pawamoy]

Great repo, much less overhead than Hypermodem and cookiecutter.

Thanks, goes straight to the heart <3

Yeah I'm suffering from the same thing since a few weeks. There's an issue open on blacken-docs to add a way to ignore parts of the markup when formatting, but the maintainer said it's a tough task and they don't have the time to fix it yet.

A quick workaround is to use markdown-exec to defer the snippet inclusion:

```python exec="1"
print('--8<-- "whatever"')
```

Not sure that's actually the worakaround, I'm on mobile, let me find the issue later :)

[gadams999]

Thanks for the workaround! That should work for me! I was able to correct by adding the following to the duty package:

    for path in paths:
        path = Path(path)  # noqa: PLW2901
        if path.is_file():
            filepaths.add(path.as_posix())
        else:
            for ext in exts:
                filepaths |= {filepath.as_posix() for filepath in path.rglob(f"*.{ext}")}
    # Apply exclude
    excl_filepaths = filepaths.copy()
    for excl in exclude:
        reg_obj = excl
        for file in excl_filepaths:
            if reg_obj.search(file):
                filepaths.remove(file)

With that [unoptimized] approach to remove the matched entries from the filepaths, this change to the project duties.py then works:

    ctx.run(
        blacken_docs.run(
            *PY_SRC_LIST,
            "docs",
            exts=["py", "md"],
            exclude=["credits.md"],
            line_length=120,
        ),
        title="Formatting docs",
        nofail=True,
    )

Reckon something like that might work?

[pawamoy]

Thanks, we can indeed consider adding an exclusion parameter to the duty callable 🙂

So here the issue I was speaking of: adamchainz/blacken-docs#193, and the workaround is:

```python exec="1" result="python"
print('--8<-- "docs/examples/model_ext.py"')
```

[gadams999]

Implemented and works, thanks!

[gadams999]

Spoke too soon. make format succeeds, but make docs host=localhost port=5000 generates the credits with the actual Python script itself and not the rendered credits tables.

[pawamoy]

Thank you for reporting back, I'll investigate :)

[pawamoy]

OK, you're right, it didn't work. Here's one that works (even uglier):

```python exec="yes"
print("""```python exec="1"\n--8<-- "scripts/gen_credits.py"\n```""")
```

[pawamoy]

I opened a PR on blacken-docs and prepared copier-pdm for it, we just have to wait now, closing 🙂

[gadams999]

Thanks for ugly hack, that's working. Will monitor the upstream repo out of interest.