Troubleshooting¤

Code blocks in admonitions (in docstrings or else) are not rendered correctly¤

To render code blocks in admonitions, you need to add the pymdownx.superfences extensions to the list of Markdown extensions in mkdocs.yml. For example:

!!! note
    Some text.

    ```bash
    echo "some code"
    ```

markdown_extensions:
- admonition
- codehilite
- pymdownx.superfences

For code blocks in docstrings, make sure to escape newlines (\n -> \\n), or prefix the entire docstring with 'r' to make it a raw-docstring: r""". Indeed, docstrings are still strings and therefore subject to how Python parses strings.

Footnotes are duplicated or overridden¤

Before version 0.14, footnotes could be duplicated over a page. Please upgrade to version 0.14 or higher.

See also:

• Issue #186
• Tabs in docstrings (from pymdownx.tabbed) are not working properly.

MkDocs warns me about links to unfound documentation files¤

A warning like this one:

WARNING - Documentation file 'reference/parsers/docstrings.md' contains a link to 'reference/parsers/pytkdocs.parsers.docstrings.Section' which is not found in the documentation files.

...generally means you used parentheses () instead of brackets [] for a cross-reference. Notice the dots in reference/parsers/pytkdocs.parsers.docstrings.Section? It shows that it's probably a cross-reference, not a direct link. It's probably written like [Section](pytkdocs.parsers.docstrings.Section) in the docs, when it should be [Section][pytkdocs.parsers.docstrings.Section].

Some objects are not rendered (they do not appear in the generated docs)¤

• Make sure the configuration options of the handler are correct. Check the documentation for Handlers to see the available options for each handler.
• Also make sure your documentation in your source code is formatted correctly. For Python code, check the supported docstring styles page.
• Re-run the Mkdocs command with -v, and carefully read any traceback.

Tabs in docstrings (from pymdownx.tabbed) are not working properly¤

Before version 0.14, multiple tab blocks injected on the same page would result in broken links: clicking on a tab would bring the user to the wrong one. Please upgrade to version 0.14 or higher.

See also:

• Issue #193
• Footnotes are duplicated or overridden.

If you are stuck on a version before 0.14, and want to use multiple tab blocks in one page, use this workaround.

// Credits to Nikolaos Zioulis (@zuru on GitHub)
function setID(){
    var tabs = document.getElementsByClassName("tabbed-set");
    for (var i = 0; i < tabs.length; i++) {
        children = tabs[i].children;
        var counter = 0;
        var iscontent = 0;
        for(var j = 0; j < children.length;j++){
            if(typeof children[j].htmlFor === 'undefined'){
                if((iscontent + 1) % 2 == 0){
                    // check if it is content
                    if(iscontent == 1){
                        btn = children[j].childNodes[1].getElementsByTagName("button");
                    }
                }
                else{
                    // if not change the id
                    children[j].id = "__tabbed_" + String(i + 1) + "_" + String(counter + 1);
                    children[j].name = "__tabbed_" + String(i + 1);
                    // make default tab open
                    if(j == 0)
                        children[j].click();
                }
                iscontent++;
            }
            else{
                // link to the correct tab
                children[j].htmlFor = "__tabbed_" + String(i+1) + "_" + String(counter + 1);
                counter ++;
            }
        }
    }
}
setID();

The generated documentation does not look good¤

Please open an ticket on the bugtracker with a detailed explanation and screenshots of the bad-looking parts. Note that you can always customize the look of mkdocstrings blocks -- through both HTML and CSS.

Warning: could not find cross-reference target¤

Make sure the referenced object is properly rendered: verify your configuration options.

For false-positives, you can wrap the text in backticks (`) to prevent mkdocstrings from trying to process it.

Python specifics¤

Nothing is rendered at all¤

Is your package available in the Python path?

See Python handler: Finding modules.

LaTeX in docstrings is not rendered correctly¤

If you are using a Markdown extension like Arithmatex Mathjax or markdown-katex to render LaTeX, add r in front of your docstring to make sure nothing is escaped. You'll still maybe have to play with escaping to get things right.

Example:

def math_function(x, y):
    r"""
    Look at these formulas:

    ```math
    f(x) = \int_{-\infty}^\infty
    \hat f(\xi)\,e^{2 \pi i \xi x}
    \,d\xi
    ```
    """

My docstrings in comments (#:) are not picked up¤

It's because we do not support type annotations in comments.

So instead of:

import enum


class MyEnum(enum.Enum):
    v1 = 1  #: The first choice.
    v2 = 2  #: The second choice.

You can use:

import enum


class MyEnum(enum.Enum):
    """My enum.

    Attributes:
        v1: The first choice.
        v2: The second choice.
    """

    v1 = 1
    v2 = 2

Or:

import enum


class MyEnum(enum.Enum):
    v1 = 1
    """The first choice."""

    v2 = 2
    """The second choice."""

My wrapped function shows documentation/code for its wrapper instead of its own¤

Use functools.wraps():

from functools import wraps


def my_decorator(function):
    """The decorator docs."""

    @wraps(function)
    def wrapped_function(*args, **kwargs):
        print("hello")
        function(*args, **kwargs)
        print("bye")

    return wrapped_function


@my_decorator
def my_function(*args, **kwargs):
    """The function docs."""
    print(*args, **kwargs)