Merge pull request #147 from hugovk/update-docs

.github/workflows/docs.yml

@@ -0,0 +1,31 @@
+name: Docs
+
+on: [push, pull_request]
+
+jobs:
+  build:
+    runs-on: ubuntu-20.04
+
+    steps:
+      - uses: actions/checkout@v2
+
+      - name: Cache
+        uses: actions/cache@v2
+        with:
+          path: ~/.cache/pip
+          key: docs-${{ hashFiles('**/tox.ini') }}
+          restore-keys: |
+            docs-
+
+      - name: Set up Python
+        uses: actions/setup-python@v2
+        with:
+          python-version: 3.8
+
+      - name: Install dependencies
+        run: |
+          python -m pip install -U pip
+          python -m pip install -U tox
+
+      - name: Docs
+        run: tox -e docs

.github/workflows/lint.yml

@@ -4,26 +4,20 @@ on: [push, pull_request]
 
 jobs:
   build:
-    runs-on: ubuntu-18.04
+    runs-on: ubuntu-20.04
 
     steps:
       - uses: actions/checkout@v2
 
-      - name: pip cache
-        uses: actions/cache@v1
+      - name: Cache
+        uses: actions/cache@v2
         with:
-          path: ~/.cache/pip
-          key: lint-pip-${{ hashFiles('**/setup.py') }}
+          path: |
+            ~/.cache/pip
+            ~/.cache/pre-commit
+          key: lint-${{ hashFiles('**/setup.py') }}-${{ hashFiles('**/.pre-commit-config.yaml') }}
           restore-keys: |
-            lint-pip-
-
-      - name: pre-commit cache
-        uses: actions/cache@v1
-        with:
-          path: ~/.cache/pre-commit
-          key: lint-pre-commit-${{ hashFiles('**/.pre-commit-config.yaml') }}
-          restore-keys: |
-            lint-pre-commit-
+            lint-
 
       - name: Set up Python
         uses: actions/setup-python@v2

.github/workflows/test.yml

@@ -41,7 +41,7 @@ jobs:
           echo "::set-output name=dir::$(pip cache dir)"
 
       - name: pip cache
-        uses: actions/cache@v1
+        uses: actions/cache@v2
         with:
           path: ${{ steps.pip-cache.outputs.dir }}
           key:

.gitignore

@@ -10,4 +10,5 @@ build
 dist
 docs/_build*
 htmlcov
+site
 tags

docs/filesize.md

@@ -0,0 +1,3 @@
+# Filesize
+
+::: humanize.filesize

docs/i18n.md

@@ -0,0 +1,3 @@
+# Internationalisation
+
+::: humanize.i18n

docs/index.md

@@ -0,0 +1,11 @@
+# humanize
+
+Welcome to the humanize API reference.
+
+* [Number](number)
+* [Time](time)
+* [Filesize](filesize)
+* [I18n](i18n)
+
+Or see [README.md](https://github.com/jmoiron/humanize/blob/master/README.md)
+for usage examples.

docs/number.md

@@ -0,0 +1,3 @@
+# Number
+
+::: humanize.number

docs/time.md

@@ -0,0 +1,3 @@
+# Time
+
+::: humanize.time

mkdocs.yml

@@ -0,0 +1,18 @@
+site_name: humanize
+site_url: https://example.com/docs/TODO
+repo_url: https://github.com/jmoiron/humanize
+theme:
+  name: "material"
+
+nav:
+  - Home: index.md
+  - Number: number.md
+  - Time: time.md
+  - Filesize: filesize.md
+  - Internationalisation: i18n.md
+
+plugins:
+  - search
+  - mkdocstrings:
+      watch:
+        - src/humanize

src/humanize/filesize.py

@@ -1,6 +1,6 @@
 #!/usr/bin/env python
 
-"""Bits & Bytes related humanization."""
+"""Bits and bytes related humanization."""
 
 suffixes = {
     "decimal": ("kB", "MB", "GB", "TB", "PB", "EB", "ZB", "YB"),
@@ -10,18 +10,18 @@
 
 
 def naturalsize(value, binary=False, gnu=False, format="%.1f"):
-    """Format a number of bytes like a human readable filesize (eg. 10 kB).
+    """Format a number of bytes like a human readable filesize (e.g. 10 kB).
 
     By default, decimal suffixes (kB, MB) are used.
 
-    Non-gnu modes are compatible with jinja2's ``filesizeformat`` filter.
+    Non-GNU modes are compatible with jinja2's `filesizeformat` filter.
 
     Args:
-        value (int, float, string): Integer to convert.
-        binary (Boolean): If `True`, uses binary suffixes (KiB, MiB) with base 2**10
-        instead of 10**3.
-        gnu (Boolean): If `True`, the binary argument is ignored and GNU-style
-        (`ls -sh` style) prefixes are used (K, M) with the 2**10 definition.
+        value (int, float, str): Integer to convert.
+        binary (bool): If `True`, uses binary suffixes (KiB, MiB) with base
+            2<sup>10</sup> instead of 10<sup>3</sup>.
+        gnu (bool): If `True`, the binary argument is ignored and GNU-style
+            (`ls -sh` style) prefixes are used (K, M) with the 2**10 definition.
         format (str): Custom formatter.
     """
     if gnu:

src/humanize/i18n.py

@@ -22,9 +22,17 @@ def get_translation():
 
 
 def activate(locale, path=None):
-    """Set 'locale' as current locale. Search for locale in directory 'path'
-    @param locale: language name, eg 'en_GB'
-    @param path: path to search for locales"""
+    """Activate internationalisation.
+
+    Set `locale` as current locale. Search for locale in directory `path`.
+
+    Args:
+        locale (str): Language name, e.g. `en_GB`.
+        path (str): Path to search for locales.
+
+    Returns:
+        dict: Translations.
+    """
     if path is None:
         path = _DEFAULT_LOCALE_PATH
 
@@ -41,19 +49,37 @@ def activate(locale, path=None):
 
 
 def deactivate():
+    """Deactivate internationalisation."""
     _CURRENT.locale = None
 
 
 def gettext(message):
+    """Get translation.
+
+    Args:
+        message (str): Text to translate.
+
+    Returns:
+        str: Translated text.
+    """
     return get_translation().gettext(message)
 
 
 def pgettext(msgctxt, message):
     """'Particular gettext' function.
-    It works with 'msgctxt' .po modifiers and allow duplicate keys with
-    different translations.
-    This GNU gettext function was added in Python 3.8, so for older versions we
-    reimplement it. It works by joining msgctx and msgid by '4' byte."""
+
+    It works with `msgctxt` .po modifiers and allows duplicate keys with different
+    translations.
+
+    Args:
+        msgctxt (str): Context of the translation.
+        message (str): Text to translate.
+
+    Returns:
+        str: Translated text.
+    """
+    # This GNU gettext function was added in Python 3.8, so for older versions we
+    # reimplement it. It works by joining `msgctx` and `message` by '4' byte.
     try:
         # Python 3.8+
         return get_translation().pgettext(msgctxt, message)
@@ -65,12 +91,34 @@ def pgettext(msgctxt, message):
 
 
 def ngettext(message, plural, num):
+    """Plural version of gettext.
+
+    Args:
+        message (str): Singlular text to translate.
+        plural (str): Plural text to translate.
+        num (str): The number (e.g. item count) to determine translation for the
+            respective grammatical number.
+
+    Returns:
+        str: Translated text.
+    """
     return get_translation().ngettext(message, plural, num)
 
 
 def gettext_noop(message):
-    """Example usage:
+    """Mark a string as a translation string without translating it.
+
+    Example usage:
+    ```python
     CONSTANTS = [gettext_noop('first'), gettext_noop('second')]
     def num_name(n):
-        return gettext(CONSTANTS[n])"""
+        return gettext(CONSTANTS[n])
+    ```
+
+    Args:
+        message (str): Text to translate in the future.
+
+    Returns:
+        str: Original text, unchanged.
+    """
     return message