Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add support for readthedocs theme #107

Closed
xuhcc opened this issue May 11, 2020 · 6 comments
Closed

Add support for readthedocs theme #107

xuhcc opened this issue May 11, 2020 · 6 comments

Comments

@xuhcc
Copy link

@xuhcc xuhcc commented May 11, 2020

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

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

@xuhcc xuhcc added the feature label May 11, 2020
@pawamoy
Copy link
Member

@pawamoy pawamoy commented May 11, 2020

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
Copy link
Author

@xuhcc xuhcc commented May 11, 2020

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
Copy link
Member

@pawamoy pawamoy commented May 11, 2020

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
Copy link
Author

@xuhcc xuhcc commented May 11, 2020

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 pawamoy added this to To do in Main board via automation Jun 8, 2020
@pawamoy pawamoy added the templates label Jun 8, 2020
pawamoy added a commit that referenced this issue Sep 28, 2020
Issue: #107
@pawamoy
Copy link
Member

@pawamoy pawamoy commented Sep 28, 2020

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
pawamoy added a commit that referenced this issue Sep 28, 2020
Issue: #107
pawamoy added a commit that referenced this issue Sep 28, 2020
Issue: #107
pawamoy added a commit that referenced this issue Sep 29, 2020
Issue: #107
pawamoy added a commit that referenced this issue Sep 29, 2020
Issue: #107
pawamoy added a commit that referenced this issue Oct 12, 2020
@pawamoy pawamoy added this to 0.14.0 in Roadmap Nov 19, 2020
@pawamoy pawamoy mentioned this issue Nov 19, 2020
0 of 2 tasks complete
pawamoy added a commit that referenced this issue Dec 6, 2020
pawamoy added a commit that referenced this issue Dec 6, 2020
Issue: #107
PR: #159
Co-authored-by: Reece Dunham <me@rdil.rocks>
pawamoy added a commit that referenced this issue Dec 6, 2020
Issue: #107
PR: #159
Co-authored-by: Reece Dunham <me@rdil.rocks>
pawamoy added a commit that referenced this issue Dec 6, 2020
Issue: #107
PR: #159
Co-authored-by: Reece Dunham <me@rdil.rocks>
pawamoy added a commit that referenced this issue Dec 6, 2020
Issue: #107
PR: #159
Co-authored-by: Reece Dunham <me@rdil.rocks>
@pawamoy
Copy link
Member

@pawamoy pawamoy commented Dec 31, 2020

Initial support has been added, and released in version 0.14.0b1.

@pawamoy pawamoy closed this Dec 31, 2020
Main board automation moved this from To do to Done Dec 31, 2020
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
Main board
  
Done
Linked pull requests

Successfully merging a pull request may close this issue.

None yet
2 participants