wip

Deployed 613f6a9 with MkDocs version: 1.4.2

Describe the bug Executed problems can produce ANSI output, which mkdocs can render using the ansi pygments formatter.

Still, this plugin does not allow us to specify which formatter to use and uses markdown.

This means that two undesired things will happen when documenting program output:

• if the output contains ANSI, the rendering will be messed
• if the output is plain text, some random keywords will be highlighted in the output

To Reproduce Steps to reproduce the behavior:

1. Gran a CLI tool that produces ANSI output, like ANSI test file
2. Add a markdown-exec block the runs it
3. What the rendered output.

Expected behavior

We need to allow exec to work similarly to already valid ANSI formatter

```ansi ```

Note that while testing, you might miss to see the colors but the ANSI will render fine. If you use inspect, you will see that class colors were added to the HTML and they will render once you add the extra css needed for them.

Screenshots

Example of an ANSI test file using the block above:

Example of undesired markdown coloring on a command line output:

Example of failure to process ANSI escapes:

System (please complete the following information):

• Markdown Exec version: 1.0.0
• Python version: 3.11
• OS: MacOS

Additional context

I did observe that there is already support for recognizing the output as JSON or HTML, so I guess it should not be too hard to add an option where we can declare the expected output format, so it would render correctly.

If you could give some hints on how this can be addressed, I would be happy to contribute a PR. I was quite pleased about the current plugin behavior and its really good documentation.

Actually just released v1.2.0 which provides the ansi extra so you don't have to depend on pygments-ansi-color and add the CSS file yourself :slightly_smiling_face:

feat: Support ANSI code blocks

Issue #11: https://github.com/pawamoy/markdown-exec/issues/11

style: Format

docs: Add missing links to pydeps diagram

chore: Prepare release 1.2.0

This is actually a limitation and is documented here: https://pawamoy.github.io/markdown-exec/usage/#wrap-result-in-a-code-block.

The console style is also a syntax highlight option, so we can't have both console and ansi at the same time. But maybe Pygments provides another option like terminal which would combine both?

I can otherwise consider lifting the limitation up and force the use of the specified result option. The user decides after all.

Hi Gerard, I've started working on it, it shouldn't take long :)

Still happens, but only when I run the mkdocs command through my task runner it seems (didn't test extensively), so don't bother too much. I'll try to isolate the real cause when I get some time :slightly_smiling_face:

Let me check, I had disabled pytermgui in the meantime :)

Yeah that look right :slightly_smiling_face:

Something like:

            if name in parent.members:
                # assigning multiple times
                # TODO: might be better to inspect
                if isinstance(node.parent, (ast.If, ast.ExceptHandler)):  # type: ignore[union-attr]
                    continue  # prefer "no-exception" case

                parent.members[name] |= labels

                # don't erase docstring
                if parent.members[name].docstring and not docstring:
                    docstring = parent.members[name].docstring

:thinking:

An MWE would look like:

# dummy.py
from griffe.loader import GriffeLoader
from griffe.extensions import VisitorExtension, Extensions, When


class DummyExtension(VisitorExtension):
    when = When.after_all

    def visit_assign(self, node) -> None:
        print("hello")  # <- put breakpoint here

Then create a venv, install Griffe and param_docs in it, and run griffe dump param_docs -e dummy.DummyExtension.

I debug in VSCode. You could start by writing a dummy Griffe extension that does almost nothing, put a breakpoint in there, and add a VSCode run configuration that runs the griffe module with the dump package -e module.DummyExtension arguments, package being either param_docs, or griffe itself, or something else. You should probably set justMyCode to false and see what Griffe is doing during the visit.

Thanks for coming back and closing!

That's great, thanks! I think providing the stylesheet is outside the scope of markdown-exec, but we can definitely put it in the docs.

wip

Context

Just trying to build mkdocstrings' docs :slightly_smiling_face: Happens with mkdocs-material 9.0.7 and 9.0.8, not 9.0.6.

Bug description

$ mkdocs build
  INFO     -  Cleaning site directory
  INFO     -  Building documentation to directory: /media/data/dev/mkdocstrings/site
  INFO     -  The following pages exist in the docs directory, but are not included in the "nav" configuration:
    - reference/autorefs/plugin.md
    - reference/autorefs/references.md
  Traceback (most recent call last):
    File "/media/data/dev/mkdocstrings/__pypackages__/3.10/bin/mkdocs", line 8, in <module>
      sys.exit(cli())
    File "/media/data/dev/mkdocstrings/__pypackages__/3.10/lib/click/core.py", line 1130, in __call__
      return self.main(*args, **kwargs)
    File "/media/data/dev/mkdocstrings/__pypackages__/3.10/lib/click/core.py", line 1055, in main
      rv = self.invoke(ctx)
    File "/media/data/dev/mkdocstrings/__pypackages__/3.10/lib/click/core.py", line 1657, in invoke
      return _process_result(sub_ctx.command.invoke(sub_ctx))
    File "/media/data/dev/mkdocstrings/__pypackages__/3.10/lib/click/core.py", line 1404, in invoke
      return ctx.invoke(self.callback, **ctx.params)
    File "/media/data/dev/mkdocstrings/__pypackages__/3.10/lib/click/core.py", line 760, in invoke
      return __callback(*args, **kwargs)
    File "/media/data/dev/mkdocstrings/__pypackages__/3.10/lib/mkdocs/__main__.py", line 250, in build_command
      build.build(cfg, dirty=not clean)
    File "/media/data/dev/mkdocstrings/__pypackages__/3.10/lib/mkdocs/commands/build.py", line 320, in build
      _build_theme_template(template, env, files, config, nav)
    File "/media/data/dev/mkdocstrings/__pypackages__/3.10/lib/mkdocs/commands/build.py", line 118, in _build_theme_template
      output = _build_template(template_name, template, files, config, nav)
    File "/media/data/dev/mkdocstrings/__pypackages__/3.10/lib/mkdocs/commands/build.py", line 97, in _build_template
      output = template.render(context)
    File "/media/data/dev/mkdocstrings/__pypackages__/3.10/lib/jinja2/environment.py", line 1301, in render
      self.environment.handle_exception()
    File "/media/data/dev/mkdocstrings/__pypackages__/3.10/lib/jinja2/environment.py", line 936, in handle_exception
      raise rewrite_traceback_stack(source=source)
    File "/media/data/dev/mkdocstrings/__pypackages__/3.10/lib/material/404.html", line 4, in top-level template code
      {% extends "main.html" %}
    File "/media/data/dev/mkdocstrings/__pypackages__/3.10/lib/material/main.html", line 4, in top-level template code
      {% extends "base.html" %}
    File "/media/data/dev/mkdocstrings/__pypackages__/3.10/lib/material/base.html", line 148, in top-level template code
      {% block site_nav %}
    File "/media/data/dev/mkdocstrings/__pypackages__/3.10/lib/material/base.html", line 156, in block 'site_nav'
      {% include "partials/nav.html" %}
    File "/media/data/dev/mkdocstrings/__pypackages__/3.10/lib/material/partials/nav.html", line 27, in top-level template code
      {% include "partials/nav-item.html" %}
    File "/media/data/dev/mkdocstrings/__pypackages__/3.10/lib/material/partials/nav-item.html", line 91, in top-level template code
      {{ render(nav_item, path, level) }}
    File "/media/data/dev/mkdocstrings/__pypackages__/3.10/lib/jinja2/runtime.py", line 777, in _invoke
      rv = self._func(*arguments)
    File "/media/data/dev/mkdocstrings/__pypackages__/3.10/lib/material/partials/nav-item.html", line 48, in template
      <nav class="md-nav" data-md-level="{{ level }}" aria-labelledby="{{ path }}_label" aria-expanded="{{ nav_item.active | tojson }}">
    File "/media/data/dev/mkdocstrings/__pypackages__/3.10/lib/jinja2/filters.py", line 1688, in do_tojson
      return htmlsafe_json_dumps(value, dumps=dumps, **kwargs)
    File "/media/data/dev/mkdocstrings/__pypackages__/3.10/lib/jinja2/utils.py", line 658, in htmlsafe_json_dumps
      dumps(obj, **kwargs)
    File "/home/pawamoy/.basher-packages/pyenv/pyenv/versions/3.10.8/lib/python3.10/json/__init__.py", line 238, in dumps
      **kw).encode(obj)
    File "/home/pawamoy/.basher-packages/pyenv/pyenv/versions/3.10.8/lib/python3.10/json/encoder.py", line 199, in encode
      chunks = self.iterencode(o, _one_shot=True)
    File "/home/pawamoy/.basher-packages/pyenv/pyenv/versions/3.10.8/lib/python3.10/json/encoder.py", line 257, in iterencode
      return _iterencode(o, 0)
    File "/home/pawamoy/.basher-packages/pyenv/pyenv/versions/3.10.8/lib/python3.10/json/encoder.py", line 179, in default
      raise TypeError(f'Object of type {o.__class__.__name__} '
  TypeError: Object of type Undefined is not JSON serializable

Related links

Reported here https://github.com/mkdocstrings/mkdocstrings/issues/528

Reproduction

example.zip

Steps to reproduce

git clone git@github.com:mkdocstrings/mkdocstrings
cd mkdocstrings
python3 -m venv venv
source venv/bin/activate
pip install pdm
pdm install -G docs
mkdocs build

Browser

No response

Before submitting

• [X] I have read and followed the bug reporting guidelines.
• [X] I have attached links to the documentation, and possibly related issues and discussions.
• [X] I assure that I have removed all customizations before submitting this bug report.
• [X] I have attached a .zip file with a minimal reproduction.

Oh, looks like it was coming from mkdocs-section-index: https://github.com/oprypin/mkdocs-section-index/releases/tag/v0.3.5. Updated the plugin locally and it works again. Closing!

Also note that you don't need to write the type in the docstring if you add a return annotation to the signature: def func() -> int: ...

Hey @w11wo, thanks for the nice report!

So, users previously asked that we support named return values. To support that, we had to use the same syntax as for parameters: name (type): Description.. It means that a return section with int: An integer. will be parsed as name=int and description=An integer.. You would have to wrap int with parentheses to have it parsed as the type instead of the name: (int): An integer..

With that said, I understand this is unexpected and non-standard, so my plan is to make this configurable. I'll eventually get to it :smile:

Right.

• if multiple docstrings: keep the last one only (current behavior I guess)
• if same attribute without docstring, don't erase previous docstring
• ideally we should combine labels: both class-attribute and instance-attribute

All this logic happens in the visitor (src/griffe/agents/visitor.py).

The bug tracker is the Todo list :D But PRs are welcome of course! I can provide more guidance :)

Hey @rodrigogiraoserrao (and @davep), thanks for opening this issue!

It's definitely not intentional, I just didn't think about this scenario :smile:

I'm OK with modifying Griffe so that it doesn't erase previous docstrings when it finds another declaration of the same class/instance attribute :)

refactor: Update code of conduct

docs: Fix grammar/typos

Merge branch 'master' of github.com:pawamoy/copier-pdm