[Bug] MardownRenderer disabling all class_prefix break the TOC

[melMass]

Hi,

I have an issue when disabling both add_method_class_prefix & add_member_class_prefix in the MarkdownRenderer, it breaks the TOC, that still looks for the fully qualified name (with the class prefix). Is this a known bug or a misconfiguration on my end?

Also is there a way to remove the prefix in the top module? (for instance in the screenshot instead of mtb.blender.mgl I want mgl)

Thanks

[melMass]

The issue is visible here:

https://pydoc-markdown.readthedocs.io/en/latest/docs/api-documentation/interfaces/#pydoc_markdown.interfaces.Processor

[NiklasRosenstein]

hey @melMass,

• Do you mean that the links in the "Table of Contents" in the middle of the page are not clickable (i.e., the #id they point to does not exist)?
• Could you share a portion of the generated Markdown? The links should point to the fully qualified name of the API object, and that should not be influenced by the two options you mentioned. 🤔

[NiklasRosenstein]

The issue is visible here:

https://pydoc-markdown.readthedocs.io/en/latest/docs/api-documentation/interfaces/#pydoc_markdown.interfaces.Processor

Here you mean that if you click on a cross-reference (e.g. "Renderer" in the section below) it does not jump to the Renderer documentation, right?

Thanks for pointing out that issue, I did not actually notice that. Looking at the Markdown that is generated for the Pydoc-Markdown API documentation, the HTML anchors are placed into the source as expected:

<a name="pydoc_markdown.interfaces.Renderer"></a>

## Renderer Objects

```python
@A.unionclass(A.unionclass.Subtypes.chain(
  A.unionclass.Subtypes.entrypoint('pydoc_markdown.interfaces.Renderer'),
  A.unionclass.Subtypes.import_()), style=A.unionclass.Style.flat)
class Renderer(PluginBase)

[view_source]

...

Which leads me to the conclusion that Hugo ignores such anchor elements (unlike GitHub flavoured Markdown or MkDocs). Maybe there is an option in Hugo to turn it on or there is an alternative syntax.

[melMass]

Do you mean that the links in the "Table of Contents" in the middle of the page are not clickable (i.e., the #id they point to does not exist)?

• Yes

Could you share a portion of the generated Markdown? The links should point to the fully qualified name of the API object, and that should not be influenced by the two options you mentioned. 🤔

But should it be? Because the headers do not seem to have any reference of the fully qualified name so I expected the opposite

[melMass]

Here you mean that if you click on a cross-reference (e.g. "Renderer" in the section below) it does not jump to the Renderer documentation, right?

Exactly, I think both issue are related but maybe I'm wrong

Which leads me to the conclusion that Hugo ignores such anchor elements (unlike GitHub flavoured Markdown or MkDocs). Maybe there is an option in Hugo to turn it on or there is an alternative syntax.

Oh ok! I was just messing around testing different commenting styles and renderers but ultimately I think I will go for MkDocs. I will still mess with Hugo a bit so if I find something relevant I will report it here.

[NiklasRosenstein]

I found this in the Hugo forums:

https://discourse.gohugo.io/t/html-code-in-md-files-not-working/22195/3

You can turn on the Hugo markup.goldmark.renderer.unsafe option which will then include the generated HTML anchors. :)

Unfortunately, I just noticed that I forgot to update the HugoConfig,additional_options field to be deserialized flat before releasing Pydoc-Markdown 4.x.

https://github.com/NiklasRosenstein/pydoc-markdown/blob/924156a45975f138ca59442ca245c550becf371a/pydoc-markdown/src/pydoc_markdown/contrib/renderers/hugo.py#L145-L149

That means with the version you most likely have you will need to use

renderer:
  type: hugo
  config:
    additional_options:
      markup:
        goldmark:
          renderer:
            unsafe: true

But that actually breaks the old behaviour from 3.x so I'm going to release a new version now where you should instead write

renderer:
  type: hugo
  config:
    markup:
      goldmark:
        renderer:
          unsafe: true

[NiklasRosenstein]

Once this completes successfully, you can upgrade your installation of Pydoc-Markdown and use the second config format. :)

https://github.com/NiklasRosenstein/pydoc-markdown/actions/runs/1111397248

I think maybe this option should be enabled by default when using the Hugo renderer in Pydoc-Markdown. 🤔

[melMass]

YES!!! I just tested and it works. So I guess this solves both the TOC when using the options mentioned and cross referencing!

Thanks a lot!

[melMass]

It's really a tiny detail but is there another attribute to remove the top module prefix (mtb_blender in the screenshot)?

[NiklasRosenstein]

Indeed, it's the same issue. 😃 Let's keep this issue open until I've figured out a way to enable this by default.

It's really a tiny detail but is there another attribute to remove the top module prefix?

Ah sorry for not responding to that earlier. There isn't right now, modules are stored without hierarchy so their name contains the fully qualified (rather than the name relative to the parent module as is the case for classes, functions, etc.). But it should be relatively easy to add. Would you like to make a contribution for this? Happy to review a PR.

Here is where you could get rid of the first level in the generated Table of Contents (i.e. by just skipping the first level of the modules and rendering the members directly):

https://github.com/NiklasRosenstein/pydoc-markdown/blob/d030fece8314ed186c5a1c3f6e20f6764fb8a28b/pydoc-markdown/src/pydoc_markdown/contrib/renderers/markdown.py#L366-L371

And here is where you could change the title for the module. You could add a new option module_no_parent_module_prefix or something like that (maybe you can come up with something more descriptive 😆 )

https://github.com/NiklasRosenstein/pydoc-markdown/blob/d030fece8314ed186c5a1c3f6e20f6764fb8a28b/pydoc-markdown/src/pydoc_markdown/contrib/renderers/markdown.py#L327-L333

[melMass]

Happy to review a PR.

Definitely! I'm on it.

[melMass]

From the develop branch right?

[NiklasRosenstein]

Yep, develop has the latest state!

[melMass]

It was easier than expected, I'm ready to issue the PR, but just a question, is it normal that the documentation (the comments) does not reflect the default values?

like here it states is enabled by default yet it is set to false here:

[NiklasRosenstein]

Nice! I'll take a look today. And no that's not expected, that just means the comment is outdated/wrong. 😄

[NiklasRosenstein]

Woops, my commit already closed the issue. But I think it's fine because the main concern is addressed. We have the PR for the module prefix topic!