pawamoy
Repos
128
Followers
258
Following
241

:blue_book: Automatic documentation from sources, for MkDocs.

1111
89

Signatures for entire Python programs. Extract the structure, the frame, the skeleton of your project, to generate API documentation or find breaking changes in your API.

130
19

Command-line tool and library to interact with an aria2c daemon process with JSON-RPC.

360
67

Copier template for Python projects managed by PDM.

34
6

A simple task runner.

41
5

Utilities to execute code blocks in Markdown files.

19
1

Events

Deployed 613f6a9 with MkDocs version: 1.4.2

Created at 14 hours ago
closed issue
Unable to specify the pygments formatter to use on received output

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.

Created at 14 hours ago
issue comment
Unable to specify the pygments formatter to use on received output

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:

Created at 14 hours ago
pawamoy create tag 1.2.0
Created at 14 hours ago

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

Created at 14 hours ago
Created at 14 hours ago
started
Created at 16 hours ago
issue comment
Setting source="console" is incompatible with result="ansi"

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.

Created at 17 hours ago
issue comment
Docstrings are not inherited

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

Created at 1 day ago
issue comment
[BUG] Non-interpreted ANSI sequence printed in the terminal

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:

Created at 1 day ago
issue comment
[BUG] Non-interpreted ANSI sequence printed in the terminal

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

Created at 1 day ago
issue comment
Question: can I do anything about docstrings for attributes being picked up from last location

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:

Created at 1 day ago
Custom template / handller for param.Parameterized classes

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.

Created at 1 day ago
Custom template / handller for param.Parameterized classes

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.

Created at 1 day ago
Handle Google style docstrings for Python properties

Thanks for coming back and closing!

Created at 1 day ago
issue comment
Unable to specify the pygments formatter to use on received output

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.

Created at 1 day ago
Created at 2 days ago
TypeError: Object of type Undefined is not JSON serializable

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

Created at 2 days ago
TypeError: Object of type Undefined is not JSON serializable

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!

Created at 2 days ago
issue comment
Non-Primitive Return Types are Incorrectly Formatted

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: ...

Created at 2 days ago
issue comment
Non-Primitive Return Types are Incorrectly Formatted

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:

Created at 2 days ago
issue comment
Question: can I do anything about docstrings for attributes being picked up from last location

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 :)

Created at 2 days ago
issue comment
Question: can I do anything about docstrings for attributes being picked up from last location

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 :)

Created at 2 days ago

refactor: Update code of conduct

docs: Fix grammar/typos

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

Created at 3 days ago