Include **only** source code using mkdocstrings.

[awgymer]

Is there a way to include in some documentation just a code block containing the source code (styled ideally) using mkdocstrings or some other mkdocs functionality?

[pawamoy]

Can you elaborate just a bit? You would like to do something like this?

::: path.to.object
    options:
       only_show_source: true

[awgymer]

Hmm so I tried this and it seems that this renders my the docs-style output still. What I want is just a codeblock with the source.

i.e.

def mymethod(a: str) -> int:
   """My Docstring"""
    return len(a)

[awgymer]

Turns out that

{% if config.extra and config.extra.show_source_only %}
  {{ class.source|highlight(language="python", linestart=class.lineno or 0, linenums=True) }}
{% else %}
  {% include "_base/class.html.jinja" with context %}
{% endif %}

would work to display the source code directly BUT I have another extension globally enabled which seems to override the behaviour in this instance and I can't find a way to switch it off locally 😞

I tried:

::: path.to.object
    options:
        extensions:
        extra:
            show_source_only: true

But only removing it from my mkdocs.yml worked, which of course borks the rest of my docs

This also causes autorefs to get mad because now there are two refs to the same object (one in my full API autodocs and one in these development docs section where I am trying to display some sections of source code).

I tried the markdown-exec option and unfortunately the output seems borked as where there is a double line break after the class docstring it causes the output to render with the class signature outside the markdown 😂

[pawamoy]

seems to override the behaviour in this instance

What do you mean by that? Is the source of the class modified somehow?

Also yes, Python packages are loaded only once (with configured Griffe extensions) and then cached, so you can't "disable" an extension after the package was already loaded. We have work in progress to make this more clear 🙂

This also causes autorefs to get mad

Huh, weird, your overridden template doesn't render any heading, so autorefs shouldn't pick them up 🤔 Try setting show_root_heading: false and show_root_toc_entry: false to your local ::: instruction 🤷

I tried the markdown-exec option and unfortunately the output seems borked as where there is a double line break after the class docstring it causes the output to render with the class signature outside the markdown 😂

Oops 😂 Not sure what you mean exactly but I'm 100% sure it's fixable 🙂 I tried it in my own docs with one of my own classes and it works well 👍

[awgymer]

What do you mean by that? Is the source of the class modified somehow?

So in this particular case, the source code is for a pydantic model and I am using griffe-pydantic. With it set globally in mkdocs.yml it seems to take precedence over the normal handler behaviour and instead of my overridden template I get the griffe-pydantic style layout. (Yes sorry this is getting increasingly more complex 🙈)

Oops 😂 Not sure what you mean exactly but I'm 100% sure it's fixable

Effectively:

Class MyModel(BaseModel):
""" The docstring"""

<REST OF THE CLASS SOURCE CODE PROPERLY FORMATTED> 

[pawamoy]

Oh you'll have to override the pydantic_model.html.jinja template then 🙂

Hard to say what goes wrong with the source, you'll have to provide a minimal reproducible example 😕

[pawamoy]

Someone on Discord (answering to you probably?) said that you could just hide everything else, and I didn't even think of that 😂

::: path.to.object
    options:
        members: no
        show_root_heading: false
        show_root_toc_entry: false
        show_bases: false
        show_signature: false
        show_docstring_attributes: false
        show_docstring_functions: false
        show_docstring_classes: false
        show_docstring_modules: false
        show_docstring_description: false
        show_docstring_examples: false
        show_docstring_other_parameters: false
        show_docstring_parameters: false
        show_docstring_raises: false
        show_docstring_receives: false
        show_docstring_returns: false
        show_docstring_warns: false
        show_docstring_yields: false
        show_source: true

It will still render the source in a "quote" admonition though.

[awgymer]

So I tried this. With griffe-pydantic I have the issue as-above. Without though I find that it doesn't render anything at all 🤔.