Documentation improvements

[mondeja]

Changes proposed in this pull request:

• Fix clamp() arguments not being correctly rendered with mkdocstrings.
• Use include-markdown plugin to include "Usage" section of README inside Home.
• Don't allow to select >>> text nodes inside codeblocks. For pycon code blocks use the recipe suggested by mkdocstrings and for python codeblocks a Javascript function with a CSS class.
• Install mkdocstrings with the legacy Python handler as extra (mkdocstrings[python-legacy]>=0.18). See About the Python handlers in mkdocstrings documentation.

[codecov-commenter]

Codecov Report

Merging #254 (4ff5673) into master (d05cf47) will not change coverage.
The diff coverage is n/a.

@@           Coverage Diff           @@
##           master     #254   +/-   ##
=======================================
  Coverage   99.68%   99.68%           
=======================================
  Files           9        9           
  Lines         635      635           
=======================================
  Hits          633      633           
  Misses          2        2           

Flag	Coverage Δ
GHA_Ubuntu	98.42% <ø> (ø)
GHA_Windows	98.11% <ø> (ø)
GHA_macOS	98.42% <ø> (ø)

Flags with carried forward coverage won't be shown. Click here to find out more.

Impacted Files	Coverage Δ
src/humanize/number.py	99.13% <ø> (ø)

---

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update d05cf47...4ff5673. Read the comment docs.

[hugovk]

Thank you very much for this, nice improvements!

---

• Don't allow to select >>> text nodes inside codeblocks. For pycon code blocks uses the recipe suggested by mkdocstrings and for python codeblocks a Javascript function with a CSS class.

I'm not sure if this is working?

For example, at /number/#humanize.number.clamp, when I click the "Copy to clipboard icon", it copies this:

>>> clamp(123.456)
'123.456'
>>> clamp(0.0001, floor=0.01)
'<0.01'
>>> clamp(0.99, format="{:.0%}", ceil=0.99)
'99%'
>>> clamp(0.999, format="{:.0%}", ceil=0.99)
'>99%'
>>> clamp(1, format=intword, floor=1e6, floor_token="under ")
'under 1.0 million'
>>> clamp(None) is None
True

Should it instead copy something like this?

clamp(123.456)
clamp(0.0001, floor=0.01)
clamp(0.99, format="{:.0%}", ceil=0.99)
clamp(0.999, format="{:.0%}", ceil=0.99)
clamp(1, format=intword, floor=1e6, floor_token="under ")
clamp(None) is None

[pawamoy]

We should probably use pycon for code blocks detected in examples, and provide the CSS rule to prevent selection of >>> and ... by default in mkdocstrings 🙂

[mondeja]

when I click the "Copy to clipboard icon", it copies this...

Opened an issue in mkdocs-material#3647 and seems that the unique solution would be to hide the "Copy to clipboard" buttons.

I've pinned pymdown-extensions>=9.2 because the function pygments_lang_class has been included in that version. Also updated the CSS selectors to only target pycon codeblocks.

[pawamoy]

I didn't know about that pygment option, I'm not sure how to include these CSS rules by default in the new Python handler now 😕

Maybe we shouldn't include them by default, as pointed out in the issue you opened.

[mondeja]

Maybe we shouldn't include them by default, as pointed out in the issue you opened.

I agree, what do you think @hugovk?

[hugovk]

Sure, fine to disable it.

The Sphinx version of the copy button can strip out >>> but I understand if it's too complex for mkdocs-material to implement. We don't have all that much code examples here.

Thanks!

[hugovk]

Thanks!