Repository navigation
Need a way to mark differences from CPython in docs #983
Description
Activity
You can most probably define custom markup patterns in Sphinx, I just don't know how...
Well, what I mean here is that we need some convention how to mark such information so it was clearly visible. Yes, ideally which would be short custom tag, which would expand to an icon with link, which when clicked, opened a page with description what it means.
But any markup which can be copy-pasted around would be good start - to save effort later to re-parse docs to find such places.
In 6d3ae56 I added a note about CPython difference using a generic admonition. The pattern to use is:
.. admonition:: Difference to CPython Text explaining difference.This is general and easy to grep for. At the moment it doesn't render as anything special, but does emit a CSS class tag for the div, so can be easily styled.
Next is to provide an easy way to link to CPython docs.
To see how it renders on RTD: http://micropython.readthedocs.org/en/latest/library/sys.html#sys.print_exception
Looks about right. Ideally, "text explaining the difference" would have some kind of background, so entire construct looked like kind of box. So, probably worth playing a bit more, but title definitely looks like expected, thanks for exploring it.
There's room to play with CSS to get it to look right. I'm sure you can box the whole thing, and even make it smaller font, etc.
I tried to add custom CSS: it works on my local machine, but doesn't on RTD server. I followed the docs on RTD for doing custom CSS, but seems that it's tricky to get it working. If anyone can fix it that would be much appreciated, otherwise this issue will remain open for some time...
Thanks for looking into this. I guess it's ok if this issue remains open and resolved in background - while it's pretty important to be resolved eventually, it's not the highest priority, even on docs side. I hope to look into it on good occasion of course.
I tried to add custom CSS: it works on my local machine, but doesn't on RTD server.
Can you please clarify whether you use default sphinx theme locally, or that RTD theme emulation package?
Can you please clarify whether you use default sphinx theme locally, or that RTD theme emulation package?
I tried both. In both cases I get (on my local machine) a black border around the CPy difference admonition (since that's in the CSS I added). But doesn't work on RTD server.
Do you have a particular URL and point out something particular to look for?
Th Firefox browser has an inspect element and you can see the final CSS for an element, and IIRC figure out where it came from.
This: http://docs.micropython.org/en/latest/library/sys.html#sys.print_exception has a "CPython difference" note, which should have custom CSS. The customstyle.css file (see https://github.com/micropython/micropython/blob/master/docs/static/customstyle.css and https://github.com/micropython/micropython/blob/master/docs/readthedocs/settings/local_settings.py) is not being recognised by the RTD server.
This file:
https://github.com/micropython/micropython/blob/master/docs/templates/layout.html#L2
refers to _static, but the name of your directory is static (no leading underscore)I made a test branch, docs-test, and tried all different combinations of underscores and not. Take a look at the source of this page http://docs.micropython.org/en/docs-test/library/sys.html and you'll see that there is no mention of custom stylesheets being included.
@dpgeorge, http://read-the-docs.readthedocs.org/en/latest/faq.html shows colored boxes, which use somewhat different syntax: https://raw.githubusercontent.com/rtfd/readthedocs.org/master/docs/faq.rst . I guess those are "predefined admonitions". Maybe we can use those for starters.
You can use note/tip admonition class and define your own title, but it's a bit of a hack and we'll have to change it later.
Ok, it can be done doing the following: a generic admonition, with a specific class that is predefined. Like this:
.. admonition:: Difference to CPython :class: attention Here be dragons.The predefined classes are, with their rendering colour:
- danger, error: red
- attention, caution, warning: orange
- hint, important, tip: green
- note: blue
I think yellow looks best for this case.
See a37656c for the fix, and http://micropython.readthedocs.org/en/latest/library/sys.html#sys.print_exception for what it looks like at RTD.
As discussed above, differences use the "adminition" tag combined with a "class", and this is used in the docs.
- added a commit that references this issue
on Jul 3, 2018
Subj. This would apply to discrepancies, extensions, etc. Need just some markup pattern, ideally simple, but which would render visibly to a user.
And this probably should go hand in hand to providing link to upstream CPython documentation for a function (which should save us a lot of typing - if we really want to have all functions documented).