Merge pull request #830 from python-babel/docs-fixes

Documentation fixes
python-babel · Jan 25, 2022 · 5279170 · 5279170
2 parents 227d1ec + dc8d383
commit 5279170
Show file tree

Hide file tree

Showing 12 changed files with 220 additions and 167 deletions.
diff --git a/.readthedocs.yml b/.readthedocs.yml
@@ -0,0 +1,19 @@
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+version: 2
+
+build:
+  os: ubuntu-20.04
+  tools:
+    python: "3.9"
+
+sphinx:
+   configuration: docs/conf.py
+
+formats:
+  - epub
+  - pdf
+
+python:
+   install:
+   - requirements: docs/requirements.txt
diff --git a/CHANGES → CHANGES.rst b/CHANGES → CHANGES.rst
diff --git a/MANIFEST.in b/MANIFEST.in
@@ -1,4 +1,4 @@
-include Makefile CHANGES LICENSE AUTHORS
+include Makefile CHANGES.rst LICENSE AUTHORS
 include conftest.py tox.ini
 include babel/global.dat
 include babel/locale-data/*.dat

diff --git a/babel/dates.py b/babel/dates.py
@@ -255,17 +255,22 @@ def get_next_timezone_transition(zone=None, dt=None):
 class TimezoneTransition(object):
     """A helper object that represents the return value from
     :func:`get_next_timezone_transition`.
+
+    :field activates:
+        The time of the activation of the timezone transition in UTC.
+    :field from_tzinfo:
+        The timezone from where the transition starts.
+    :field to_tzinfo:
+        The timezone for after the transition.
+    :field reference_date:
+        The reference date that was provided.  This is the `dt` parameter
+        to the :func:`get_next_timezone_transition`.
     """
 
     def __init__(self, activates, from_tzinfo, to_tzinfo, reference_date=None):
-        #: the time of the activation of the timezone transition in UTC.
         self.activates = activates
-        #: the timezone from where the transition starts.
         self.from_tzinfo = from_tzinfo
-        #: the timezone for after the transition.
         self.to_tzinfo = to_tzinfo
-        #: the reference date that was provided.  This is the `dt` parameter
-        #: to the :func:`get_next_timezone_transition`.
         self.reference_date = reference_date
 
     @property

diff --git a/babel/messages/extract.py b/babel/messages/extract.py
@@ -512,8 +512,7 @@ def extract_javascript(fileobj, keywords, comment_tags, options):
     :param options: a dictionary of additional options (optional)
                     Supported options are:
                     * `jsx` -- set to false to disable JSX/E4X support.
-                    * `template_string` -- set to false to disable ES6
-                                           template string support.
+                    * `template_string` -- set to false to disable ES6 template string support.
     """
     from babel.messages.jslexer import Token, tokenize, unquote_string
     funcname = message_lineno = None

diff --git a/docs/api/dates.rst b/docs/api/dates.rst
@@ -42,6 +42,8 @@ Timezone Functionality
 
     A timezone object for the computer's local timezone.
 
+.. autoclass:: TimezoneTransition
+
 Data Access
 -----------
 

diff --git a/docs/changelog.rst b/docs/changelog.rst
@@ -1 +1 @@
-.. include:: ../CHANGES
+.. include:: ../CHANGES.rst
diff --git a/docs/cmdline.rst b/docs/cmdline.rst
@@ -14,9 +14,9 @@ systems.
 When properly installed, Babel provides a script called ``pybabel``::
 
     $ pybabel --help
-    usage: pybabel command [options] [args]
+    Usage: pybabel command [options] [args]
 
-    options:
+    Options:
       --version       show program's version number and exit
       -h, --help      show this help message and exit
       --list-locales  print all known locales and exit
@@ -40,24 +40,25 @@ The ``compile`` sub-command can be used to compile translation catalogs into
 binary MO files::
 
     $ pybabel compile --help
-    usage: pybabel compile [options]
+    Usage: pybabel compile [options]
 
     compile message catalogs to MO files
 
-    options:
+    Options:
       -h, --help            show this help message and exit
       -D DOMAIN, --domain=DOMAIN
-                            domain of MO and PO files (default 'messages')
-      -d DIR, --directory=DIR
-                            base directory of catalog files
-      -l LOCALE, --locale=LOCALE
-                            locale of the catalog
-      -i FILE, --input-file=FILE
+                            domains of PO files (space separated list, default
+                            'messages')
+      -d DIRECTORY, --directory=DIRECTORY
+                            path to base directory containing the catalogs
+      -i INPUT_FILE, --input-file=INPUT_FILE
                             name of the input file
-      -o FILE, --output-file=FILE
+      -o OUTPUT_FILE, --output-file=OUTPUT_FILE
                             name of the output file (default
                             '<output_dir>/<locale>/LC_MESSAGES/<domain>.mo')
-      -f, --use-fuzzy       also include fuzzy translations (default False)
+      -l LOCALE, --locale=LOCALE
+                            locale of the catalog to compile
+      -f, --use-fuzzy       also include fuzzy translations
       --statistics          print statistics about translations
 
 If ``directory`` is specified, but ``output-file`` is not, the default filename
@@ -77,39 +78,53 @@ The ``extract`` sub-command can be used to extract localizable messages from
 a collection of source files::
 
     $ pybabel extract --help
-    usage: pybabel extract [options] dir1 <dir2> ...
+    Usage: pybabel extract [options] <input-paths>
 
     extract messages from source files and generate a POT file
 
-    options:
+    Options:
       -h, --help            show this help message and exit
-      --charset=CHARSET     charset to use in the output (default "utf-8")
-      -k KEYWORDS, --keyword=KEYWORDS
-                            keywords to look for in addition to the defaults. You
-                            can specify multiple -k flags on the command line.
+      --charset=CHARSET     charset to use in the output file (default "utf-8")
+      -k KEYWORDS, --keywords=KEYWORDS, --keyword=KEYWORDS
+                            space-separated list of keywords to look for in
+                            addition to the defaults (may be repeated multiple
+                            times)
       --no-default-keywords
                             do not include the default keywords
-      -F MAPPING_FILE, --mapping=MAPPING_FILE
-                            path to the extraction mapping file
+      -F MAPPING_FILE, --mapping-file=MAPPING_FILE, --mapping=MAPPING_FILE
+                            path to the mapping configuration file
       --no-location         do not include location comments with filename and
                             line number
+      --add-location=ADD_LOCATION
+                            location lines format. If it is not given or "full",
+                            it generates the lines with both file name and line
+                            number. If it is "file", the line number part is
+                            omitted. If it is "never", it completely suppresses
+                            the lines (same as --no-location).
       --omit-header         do not include msgid "" entry in header
-      -o OUTPUT, --output=OUTPUT
-                            path to the output POT file
+      -o OUTPUT_FILE, --output-file=OUTPUT_FILE, --output=OUTPUT_FILE
+                            name of the output file
       -w WIDTH, --width=WIDTH
                             set output line width (default 76)
       --no-wrap             do not break long message lines, longer than the
                             output line width, into several lines
       --sort-output         generate sorted output (default False)
       --sort-by-file        sort output by file location (default False)
-      --msgid-bugs-address=EMAIL@ADDRESS
+      --msgid-bugs-address=MSGID_BUGS_ADDRESS
                             set report address for msgid
       --copyright-holder=COPYRIGHT_HOLDER
                             set copyright holder in output
-      -c TAG, --add-comments=TAG
+      --project=PROJECT     set project name in output
+      --version=VERSION     set project version in output
+      -c ADD_COMMENTS, --add-comments=ADD_COMMENTS
                             place comment block with TAG (or those preceding
-                            keyword lines) in output file. One TAG per argument
-                            call
+                            keyword lines) in output file. Separate multiple TAGs
+                            with commas(,)
+      -s, --strip-comments, --strip-comment-tags
+                            strip the comment TAGs from the comments.
+      --input-dirs=INPUT_DIRS
+                            alias for input-paths (does allow files as well as
+                            directories).
 
 
 init
@@ -119,24 +134,27 @@ The `init` sub-command creates a new translations catalog based on a PO
 template file::
 
     $ pybabel init --help
-    usage: pybabel init [options]
+    Usage: pybabel init [options]
 
     create new message catalogs from a POT file
 
-    options:
+    Options:
       -h, --help            show this help message and exit
       -D DOMAIN, --domain=DOMAIN
                             domain of PO file (default 'messages')
-      -i FILE, --input-file=FILE
+      -i INPUT_FILE, --input-file=INPUT_FILE
                             name of the input file
-      -d DIR, --output-dir=DIR
+      -d OUTPUT_DIR, --output-dir=OUTPUT_DIR
                             path to output directory
-      -o FILE, --output-file=FILE
+      -o OUTPUT_FILE, --output-file=OUTPUT_FILE
                             name of the output file (default
                             '<output_dir>/<locale>/LC_MESSAGES/<domain>.po')
       -l LOCALE, --locale=LOCALE
                             locale for the new localized catalog
-
+      -w WIDTH, --width=WIDTH
+                            set output line width (default 76)
+      --no-wrap             do not break long message lines, longer than the
+                            output line width, into several lines
 
 update
 ======
@@ -145,29 +163,36 @@ The `update` sub-command updates an existing new translations catalog based on
 a PO template file::
 
     $ pybabel update --help
-    usage: pybabel update [options]
+    Usage: pybabel update [options]
 
     update existing message catalogs from a POT file
 
-    options:
+    Options:
       -h, --help            show this help message and exit
       -D DOMAIN, --domain=DOMAIN
                             domain of PO file (default 'messages')
-      -i FILE, --input-file=FILE
+      -i INPUT_FILE, --input-file=INPUT_FILE
                             name of the input file
-      -d DIR, --output-dir=DIR
-                            path to output directory
-      -o FILE, --output-file=FILE
+      -d OUTPUT_DIR, --output-dir=OUTPUT_DIR
+                            path to base directory containing the catalogs
+      -o OUTPUT_FILE, --output-file=OUTPUT_FILE
                             name of the output file (default
                             '<output_dir>/<locale>/LC_MESSAGES/<domain>.po')
+      --omit-header         do not include msgid  entry in header
       -l LOCALE, --locale=LOCALE
-                            locale of the translations catalog
-      --ignore-obsolete     do not include obsolete messages in the output
-                            (default False)
+                            locale of the catalog to compile
+      -w WIDTH, --width=WIDTH
+                            set output line width (default 76)
+      --no-wrap             do not break long message lines, longer than the
+                            output line width, into several lines
+      --ignore-obsolete     whether to omit obsolete messages from the output
+      --init-missing        if any output files are missing, initialize them first
       -N, --no-fuzzy-matching
-                            do not use fuzzy matching (default False)
-      --previous            keep previous msgids of translated messages (default
-                            False)
+                            do not use fuzzy matching
+      --update-header-comment
+                            update target header comment
+      --previous            keep previous msgids of translated messages
+
 
 If ``output_dir`` is specified, but ``output-file`` is not, the default
 filename of the output file will be::

diff --git a/docs/conf.py b/docs/conf.py
@@ -224,8 +224,7 @@
 # One entry per manual page. List of tuples
 # (source start file, name, description, authors, manual section).
 man_pages = [
-    ('index_', 'babel', u'Babel Documentation',
-     [u'The Babel Team'], 1)
+    ('index', 'babel', u'Babel Documentation', [u'The Babel Team'], 1),
 ]
 
 # If true, show URL addresses after external links.

diff --git a/docs/numbers.rst b/docs/numbers.rst
@@ -18,13 +18,16 @@ Examples:
 
 .. code-block:: pycon
 
+    # Numbers with decimal places
     >>> format_decimal(1.2345, locale='en_US')
     u'1.234'
     >>> format_decimal(1.2345, locale='sv_SE')
     u'1,234'
+    # Integers with thousand grouping
     >>> format_decimal(12345, locale='de_DE')
     u'12.345'
-
+    >>> format_decimal(12345678, locale='de_DE')
+    u'12.345.678'
 
 Pattern Syntax
 ==============

diff --git a/docs/requirements.txt b/docs/requirements.txt
@@ -0,0 +1 @@
+Sphinx~=4.4.0
diff --git a/scripts/make-release.py b/scripts/make-release.py
@@ -20,7 +20,7 @@
 
 
 def parse_changelog():
-    with open('CHANGES') as f:
+    with open('CHANGES.rst') as f:
         lineiter = iter(f)
         for line in lineiter:
             match = re.search(r'^Version\s+(.*)', line.strip())