Add support for readthedocs theme

[xuhcc]

Is your feature request related to a problem? Please describe.

readthedocs is a popular theme, it would be nice to have it supported.

[pawamoy]

I'll let users vote with 👍 on the issue 🙂 (right now other issues need my attention!)

Also, did you actually try mkdocstrings with the readthedocs theme of mkdocs? What issues could you see in the rendering? I expect the code blocks not to render perfectly.

You can also try hacking the material theme with the custom_templates option, which will let you override specific templates. Just copy paste the src/mkdocstrings/templates folder into your docs folder and add this to your config:

plugins:
  - mkdocstrings:
      custom_templates: docs/templates

Then you can try and fix the parts that are not rendered properly, or play with custom CSS rules to make it look more like RTD.

[xuhcc]

Also, did you actually try mkdocstrings with the readthedocs theme of mkdocs? What issues could you see in the rendering? I expect the code blocks not to render perfectly.

Yes, the code blocks are rendered incorrectly. And I would like to add some padding to table cells: https://xuhcc.github.io/beancount-docs/api_reference/beancount.ops.html

[pawamoy]

About code blocks, I still don't know how to fix that. We should chat with the mkdocs maintainers to see exactly how their built-in themes are rendering code blocks, so we can do the same in a readthedocs theme here.

As for table cells padding, you can tweak it as much as you want with extra CSS files:

# mkdocs.yml

extra_css:
  - docs/custom.css

Note that I recommend these CSS rules for the Material theme: https://pawamoy.github.io/mkdocstrings/handlers/python/#recommended-style, and this might be why you have no padding in table cells. Try to remove the last part if you have copied these rules into your project:

/* Remove these rules */
/* For pieces of Markdown rendered in table cells. */
td p {
  margin-top: 0 !important;
  margin-bottom: 0 !important;
}

Or just change the 0-margin rules with positive padding ones 🙂

[xuhcc]

Turned out that tables were rendering incorrectly due to the bug in mkdocs 1.1.

And this rule fixes rendering of code blocks in headings:

.doc-heading code {
    white-space: normal;
}

[pawamoy]

Hey everybody, I just opened a PR to add support for the ReadTheDocs theme: #159. Please try it and let me know if something could be improved. It's not as beautiful as with Material for MkDocs, but I fixed the most obvious things. If you try it, don't forget to copy the new CSS rules (from the docs in the PR).

pip install git+https://github.com/pawamoy/mkdocstrings@add-readthedocs-theme