Documentation improvements

README.md

@@ -42,11 +42,13 @@ human-readable size or throughput. It is localized to:
 
 [https://python-humanize.readthedocs.io](https://python-humanize.readthedocs.io)
 
+<!-- usage-start -->
+
 ## Usage
 
 ### Integer humanization
 
-```pycon
+```python
 >>> import humanize
 >>> humanize.intcomma(12345)
 '12,345'
@@ -62,7 +64,7 @@ human-readable size or throughput. It is localized to:
 
 ### Date & time humanization
 
-```pycon
+```python
 >>> import humanize
 >>> import datetime as dt
 >>> humanize.naturalday(dt.datetime.now())
@@ -83,7 +85,7 @@ human-readable size or throughput. It is localized to:
 
 ### Precise time delta
 
-```pycon
+```python
 >>> import humanize
 >>> import datetime as dt
 >>> delta = dt.timedelta(seconds=3633, days=2, microseconds=123000)
@@ -99,13 +101,13 @@ human-readable size or throughput. It is localized to:
 
 If seconds are too large, set `minimum_unit` to milliseconds or microseconds:
 
-```pycon
+```python
 >>> import humanize
 >>> import datetime as dt
 >>> humanize.naturaldelta(dt.timedelta(seconds=2))
 '2 seconds'
 ```
-```pycon
+```python
 >>> delta = dt.timedelta(milliseconds=4)
 >>> humanize.naturaldelta(delta)
 'a moment'
@@ -114,7 +116,7 @@ If seconds are too large, set `minimum_unit` to milliseconds or microseconds:
 >>> humanize.naturaldelta(delta, minimum_unit="microseconds")
 '4 milliseconds'
 ```
-```pycon
+```python
 >>> humanize.naturaltime(delta)
 'now'
 >>> humanize.naturaltime(delta, minimum_unit="milliseconds")
@@ -125,7 +127,7 @@ If seconds are too large, set `minimum_unit` to milliseconds or microseconds:
 
 ### File size humanization
 
-```pycon
+```python
 >>> import humanize
 >>> humanize.naturalsize(1_000_000)
 '1.0 MB'
@@ -137,7 +139,7 @@ If seconds are too large, set `minimum_unit` to milliseconds or microseconds:
 
 ### Human-readable floating point numbers
 
-```pycon
+```python
 >>> import humanize
 >>> humanize.fractional(1/3)
 '1/3'
@@ -153,7 +155,7 @@ If seconds are too large, set `minimum_unit` to milliseconds or microseconds:
 
 ### Scientific notation
 
-```pycon
+```python
 >>> import humanize
 >>> humanize.scientific(0.3)
 '3.00 x 10⁻¹'
@@ -173,7 +175,7 @@ If seconds are too large, set `minimum_unit` to milliseconds or microseconds:
 
 How to change locale at runtime:
 
-```pycon
+```python
 >>> import humanize
 >>> import datetime as dt
 >>> humanize.naturaltime(dt.timedelta(seconds=3))
@@ -189,7 +191,7 @@ How to change locale at runtime:
 You can pass additional parameter `path` to `activate` to specify a path to search
 locales in.
 
-```pycon
+```python
 >>> import humanize
 >>> humanize.i18n.activate("xx_XX")
 <...>
@@ -198,6 +200,8 @@ FileNotFoundError: [Errno 2] No translation file found for domain: 'humanize'
 <gettext.GNUTranslations instance ...>
 ```
 
+<!-- usage-end -->
+
 How to add new phrases to existing locale files:
 
 ```console

docs/css/code_select.css

@@ -0,0 +1,9 @@
+/* Don't allow to select >>> in ```pycon``` code blocks */
+.highlight .gp, .highlight .go { /* Generic.Prompt, Generic.Output */
+    user-select: none;
+}
+
+/* >>> selection in ```python``` code blocks is handled with Javascript */
+.no-user-select {
+    user-select: none;
+}

docs/index.md

@@ -7,5 +7,9 @@ Welcome to the humanize API reference.
 * [Filesize](filesize)
 * [I18n](i18n)
 
-For usage examples see
-[README.md](https://github.com/jmoiron/humanize/blob/master/README.md).
+{%
+   include-markdown "../README.md"
+   start="<!-- usage-start -->"
+   end="<!-- usage-end -->"
+   comments=false
+%}

docs/js/code_select.js

@@ -0,0 +1,22 @@
+/**
+ * Disable user selection for '>>>' nodes inside code blocks.
+ */
+function disablePyConsolePromptsUserSelection() {
+    const spans = document.getElementsByClassName('o');
+    for (let i=0; i<spans.length; i++) {
+        const span = spans[i];
+        if (span.innerText === '>>>') {
+            // if the next is a text node with a space as content
+            // move the space to the span so it will not be selectable
+            if (span.nextSibling.data === ' ') {
+                span.innerText = '>>> '
+                span.nextSibling.data = ''
+            }
+            span.classList.add('no-user-select');
+        }
+    }
+}
+
+document.addEventListener("DOMContentLoaded", function() {
+    disablePyConsolePromptsUserSelection();
+})

docs/requirements.txt

@@ -1,3 +1,6 @@
 mkdocs>=1.1
 mkdocs-material
-mkdocstrings
+mkdocstrings[python-legacy]>=0.18
+mkdocs-include-markdown-plugin
+pygments
+pymdown-extensions

mkdocs.yml

@@ -2,7 +2,7 @@ site_name: humanize
 site_url: https://python-humanize.readthedocs.io
 repo_url: https://github.com/jmoiron/humanize
 theme:
-  name: "material"
+  name: material
 
 nav:
   - Home: index.md
@@ -16,3 +16,14 @@ plugins:
   - mkdocstrings:
       watch:
         - src/humanize
+  - include-markdown
+
+markdown_extensions:
+  - pymdownx.highlight:
+      use_pygments: true
+  - pymdownx.superfences
+
+extra_css:
+  - css/code_select.css
+extra_javascript:
+  - js/code_select.js

src/humanize/number.py

@@ -421,9 +421,9 @@ def clamp(value, format="{:}", floor=None, ceil=None, floor_token="<", ceil_toke
         floor (int, float): Smallest value before clamping.
         ceil (int, float): Largest value before clamping.
         floor_token (str): If value is smaller than floor, token will be prepended
-        to output.
+            to output.
         ceil_token (str): If value is larger than ceil, token will be prepended
-        to output.
+            to output.
 
     Returns:
         str: Formatted number. The output is clamped between the indicated floor and