Documentation improvements (#254)

README.md

@@ -42,6 +42,8 @@ human-readable size or throughput. It is localized to:
 
 [https://python-humanize.readthedocs.io](https://python-humanize.readthedocs.io)
 
+<!-- usage-start -->
+
 ## Usage
 
 ### Integer humanization
@@ -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,10 @@
+/* Don't allow to select >>> in ```pycon``` code blocks */
+.language-pycon .gp,
+.language-pycon .go {
+  user-select: none;
+}
+
+/* Hide "Copy to clipboard" buttons in ```pycon``` code blocks */
+.highlight.language-pycon .md-clipboard {
+  display: 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/requirements.txt

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

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,13 @@ plugins:
   - mkdocstrings:
       watch:
         - src/humanize
+  - include-markdown
+
+markdown_extensions:
+  - pymdownx.highlight:
+      use_pygments: true
+      pygments_lang_class: true
+  - pymdownx.superfences
+
+extra_css:
+  - css/code_select.css

src/humanize/number.py

@@ -417,13 +417,13 @@ def clamp(value, format="{:}", floor=None, ceil=None, floor_token="<", ceil_toke
     Args:
         value (int, float): Input number.
         format (str OR callable): Can either be a formatting string, or a callable
-        function than receives value and returns a string.
+            function that receives value and returns a string.
         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