Skip to content

Documentation improvements#254

Merged
hugovk merged 3 commits intojmoiron:masterfrom
mondeja:doc-improvements
Mar 6, 2022
Merged

Documentation improvements#254
hugovk merged 3 commits intojmoiron:masterfrom
mondeja:doc-improvements

Conversation

@mondeja
Copy link
Copy Markdown
Contributor

@mondeja mondeja commented Feb 22, 2022

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

codecov-commenter commented Feb 22, 2022

Codecov Report

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

Impacted file tree graph

@@           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.

Copy link
Copy Markdown
Collaborator

@hugovk hugovk left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

@hugovk hugovk added changelog: Added For new features documentation Improvements or additions to documentation labels Feb 27, 2022
@pawamoy
Copy link
Copy Markdown

pawamoy commented Mar 1, 2022

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

mondeja commented Mar 1, 2022

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

pawamoy commented Mar 1, 2022

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

mondeja commented Mar 1, 2022

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

I agree, what do you think @hugovk?

@hugovk
Copy link
Copy Markdown
Collaborator

hugovk commented Mar 5, 2022

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!

@mondeja mondeja requested a review from hugovk March 6, 2022 01:50
@hugovk hugovk merged commit e4681fa into jmoiron:master Mar 6, 2022
@hugovk
Copy link
Copy Markdown
Collaborator

hugovk commented Mar 6, 2022

Thanks!

@mondeja mondeja deleted the doc-improvements branch March 6, 2022 12:05
kraj pushed a commit to YoeDistro/meta-openembedded that referenced this pull request May 27, 2022
Changelog:
==========
Added
------
    Support Python 3.11 (openembedded#13)
    Add Arabic language (jmoiron/humanize#256)
    Docs: add dark mode toggle and default to system preference (jmoiron/humanize#255)
    Documentation improvements (jmoiron/humanize#254)

Changed
-------
    Update repo links (openembedded#2)

Fixed
-------
    Removed VERSION from __all__ (openembedded#11)

Signed-off-by: Zheng Ruoqin <zhengrq.fnst@fujitsu.com>
Signed-off-by: Khem Raj <raj.khem@gmail.com>
kraj pushed a commit to YoeDistro/meta-openembedded that referenced this pull request May 27, 2022
Changelog:
==========
Added
------
    Support Python 3.11 (openembedded#13)
    Add Arabic language (jmoiron/humanize#256)
    Docs: add dark mode toggle and default to system preference (jmoiron/humanize#255)
    Documentation improvements (jmoiron/humanize#254)

Changed
-------
    Update repo links (openembedded#2)

Fixed
-------
    Removed VERSION from __all__ (openembedded#11)

Signed-off-by: Zheng Ruoqin <zhengrq.fnst@fujitsu.com>
Signed-off-by: Khem Raj <raj.khem@gmail.com>
kraj pushed a commit to YoeDistro/meta-openembedded that referenced this pull request May 27, 2022
Changelog:
==========
Added
------
    Support Python 3.11 (openembedded#13)
    Add Arabic language (jmoiron/humanize#256)
    Docs: add dark mode toggle and default to system preference (jmoiron/humanize#255)
    Documentation improvements (jmoiron/humanize#254)

Changed
-------
    Update repo links (openembedded#2)

Fixed
-------
    Removed VERSION from __all__ (openembedded#11)

Signed-off-by: Zheng Ruoqin <zhengrq.fnst@fujitsu.com>
Signed-off-by: Khem Raj <raj.khem@gmail.com>
kraj pushed a commit to YoeDistro/meta-openembedded that referenced this pull request May 28, 2022
Changelog:
==========
Added
------
    Support Python 3.11 (openembedded#13)
    Add Arabic language (jmoiron/humanize#256)
    Docs: add dark mode toggle and default to system preference (jmoiron/humanize#255)
    Documentation improvements (jmoiron/humanize#254)

Changed
-------
    Update repo links (openembedded#2)

Fixed
-------
    Removed VERSION from __all__ (openembedded#11)

Signed-off-by: Zheng Ruoqin <zhengrq.fnst@fujitsu.com>
Signed-off-by: Khem Raj <raj.khem@gmail.com>
kraj pushed a commit to YoeDistro/meta-openembedded that referenced this pull request May 28, 2022
Changelog:
==========
Added
------
    Support Python 3.11 (openembedded#13)
    Add Arabic language (jmoiron/humanize#256)
    Docs: add dark mode toggle and default to system preference (jmoiron/humanize#255)
    Documentation improvements (jmoiron/humanize#254)

Changed
-------
    Update repo links (openembedded#2)

Fixed
-------
    Removed VERSION from __all__ (openembedded#11)

Signed-off-by: Zheng Ruoqin <zhengrq.fnst@fujitsu.com>
Signed-off-by: Khem Raj <raj.khem@gmail.com>
kraj pushed a commit to YoeDistro/meta-openembedded that referenced this pull request May 28, 2022
Changelog:
==========
Added
------
    Support Python 3.11 (openembedded#13)
    Add Arabic language (jmoiron/humanize#256)
    Docs: add dark mode toggle and default to system preference (jmoiron/humanize#255)
    Documentation improvements (jmoiron/humanize#254)

Changed
-------
    Update repo links (openembedded#2)

Fixed
-------
    Removed VERSION from __all__ (openembedded#11)

Signed-off-by: Zheng Ruoqin <zhengrq.fnst@fujitsu.com>
Signed-off-by: Khem Raj <raj.khem@gmail.com>
kraj pushed a commit to YoeDistro/meta-openembedded that referenced this pull request May 28, 2022
Changelog:
==========
Added
------
    Support Python 3.11 (openembedded#13)
    Add Arabic language (jmoiron/humanize#256)
    Docs: add dark mode toggle and default to system preference (jmoiron/humanize#255)
    Documentation improvements (jmoiron/humanize#254)

Changed
-------
    Update repo links (openembedded#2)

Fixed
-------
    Removed VERSION from __all__ (openembedded#11)

Signed-off-by: Zheng Ruoqin <zhengrq.fnst@fujitsu.com>
Signed-off-by: Khem Raj <raj.khem@gmail.com>
kraj pushed a commit to YoeDistro/meta-openembedded that referenced this pull request May 29, 2022
Changelog:
==========
Added
------
    Support Python 3.11 (openembedded#13)
    Add Arabic language (jmoiron/humanize#256)
    Docs: add dark mode toggle and default to system preference (jmoiron/humanize#255)
    Documentation improvements (jmoiron/humanize#254)

Changed
-------
    Update repo links (openembedded#2)

Fixed
-------
    Removed VERSION from __all__ (openembedded#11)

Signed-off-by: Zheng Ruoqin <zhengrq.fnst@fujitsu.com>
Signed-off-by: Khem Raj <raj.khem@gmail.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

changelog: Added For new features documentation Improvements or additions to documentation

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants