Repository navigation
Need a way to mark differences from CPython in docs #983
Description
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).
Activity
dpgeorge commentedon Nov 26, 2014
You can most probably define custom markup patterns in Sphinx, I just don't know how...
pfalcon commentedon Dec 6, 2014
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.
dpgeorge commentedon Dec 6, 2014
How about a generic admonition: http://docutils.sourceforge.net/docs/ref/rst/directives.html#admonitions . See also http://stackoverflow.com/questions/9162891/define-mark-up-for-generic-sphinx-admonitions-with-a-specific-title
dpgeorge commentedon Dec 19, 2014
In 6d3ae56 I added a note about CPython difference using a generic admonition. The pattern to use is:
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.
dpgeorge commentedon Dec 19, 2014
To see how it renders on RTD: http://micropython.readthedocs.org/en/latest/library/sys.html#sys.print_exception
pfalcon commentedon Dec 19, 2014
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.
dpgeorge commentedon Dec 19, 2014
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.
dpgeorge commentedon Dec 21, 2014
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...
pfalcon commentedon Dec 21, 2014
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.
Can you please clarify whether you use default sphinx theme locally, or that RTD theme emulation package?
dpgeorge commentedon Dec 21, 2014
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.
dhylands commentedon Dec 21, 2014
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.
dpgeorge commentedon Dec 21, 2014
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.
dhylands commentedon Dec 21, 2014
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)
dpgeorge commentedon Dec 21, 2014
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.
pfalcon commentedon Dec 21, 2014
@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.
dpgeorge commentedon Dec 22, 2014
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.
dpgeorge commentedon Dec 22, 2014
Ok, it can be done doing the following: a generic admonition, with a specific class that is predefined. Like this:
The predefined classes are, with their rendering colour:
I think yellow looks best for this case.
dpgeorge commentedon Dec 22, 2014
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.
dpgeorge commentedon Jun 26, 2017
As discussed above, differences use the "adminition" tag combined with a "class", and this is used in the docs.
Merge pull request micropython#983 from adafruit/tannewt-patch-1