Improved docs

dakrauth · Feb 3, 2025 · 145f64e · 145f64e
1 parent 007fd20
commit 145f64e
Show file tree

Hide file tree

Showing 8 changed files with 250 additions and 95 deletions.
diff --git a/Justfile b/Justfile
@@ -26,6 +26,7 @@ update:
     {{PIP}} install -U \
         build \
         pytest \
+        docutils \
         pytest-sugar \
         pytest-clarity \
         freezegun \
@@ -132,3 +133,8 @@ strftime:
         f"Format Specifiers:\n{pt.get_string()}\n\n"
         "Notes:\n* - Locale-dependent\n+ - C99 extension\n! - when extension"
     )
+
+# Preview README.rst
+docs:
+    rst2html5 --output README.html README.rst
+    open README.html
diff --git a/README.rst b/README.rst
@@ -1,3 +1,4 @@
+=========
 when 🌐🕐
 =========
 
@@ -17,64 +18,113 @@ Scenario
 --------
 
 Your favorite sporting event, concert, performance, conference, or symposium is happening
-in Ulan Bator and all you know is the time of event is relative to the location city or time zone. 
-But wait! You need to know when that occurs relative to you while traveling to Seoul or Paris.
+in Ulan Bator and all you know is the time of event relative to the city or time zone. 
+So what time is that for you in your local time? What time did it or will it occur at some
+other time? What about for your friends in other locations around the world?
+
+Features
+--------
+
+``when`` can refer to source and target locations via the ``--source`` and ``--target`` specifiers.
+
+*   ``when`` can download a GeoNames_ cities database for referencing locations by city name
+*   All IANA time zone definitions are available, as well as the most common time zone aliases (i.e.: ``EST`` => ``US/Eastern``)
+*   Display current lunar state
+*   List common holidays for a given country and/or year (US or configurable)
+*   Show dates for full moons
+*   Extensive configuration options for results
+*   JSON output
 
 Installation
-------------
+============
+
+Install from PyPI:
 
-Install from PyPI::
+.. code:: bash
 
     $ pip install when
 
-or using pipx_::
+or using pipx_:
+
+.. code:: bash
 
     $ pipx install when
 
-or::
+or:
+
+.. code:: bash
 
     $ pipx install git+https://github.com/dakrauth/when.git
 
-.. _pipx: https://pypa.github.io/pipx/
+.. note::
+
+    Once installed, if you wish to utilize ``when``'s full capabilities, you should
+    install the GeoNames cities database as describe next.
 
-To access city names, you must install the cities database::
+
+
+Database installation
+---------------------
+
+To access city names, you need to install the cities database after installing the ``when`` application:
+
+.. code:: bash
 
     when --db [options]
 
-For ``options``:
+Where ``options`` are:
+
+* ``--db-size``: You can specify a database down size by using one of the following:
+
+  * ``sm`` - cities with population > 15,000 + country capitals (~2.9M download, ~2M DB)
+  * ``md`` - **default**, same as ``sm``, plus:
+
+    * cities with population > 5,000 (~4.8M download, ~3.1M DB)
+    * seat of first-order admin division, i.e. US state
+
+  * ``lg`` - same as ``md``, plus:
+
+    * cities with population > 1,000 (~9.5M download, ~5.8M DB)
+    * seat of admin division down to third level (counties)
+
+  * ``xl`` - same as ``lg``, plus:
+
+    * cities with population > 500 (~12.1M download, ~7.2M DB)
+    * seat of admin division down to fourth order 
 
-You can specify minimum city size by adding ``--size SIZE``, where *SIZE* can be one of:
+* ``--db-pop``: Filter non-admin division seats providing a minimum city population size
+* ``--db-force``: Force an existing database to be overwritten
 
-- ``15000`` - cities with population > 15000 or country capitals
-- ``5000`` - cities with population > 5000 or seat of first-order admin division, i.e. US state
-- ``1000`` - cities with population > 1000 or seat of third order admin division
-- ``500`` - cities with population > 500 or seat of fourth-order admin division
+Database Usage
+==============
 
-Additionally, you can filter non-admin division seats using ``--pop POP``.
+* Search: ``--db-search``
 
-The appropriate GeoNames Gazetteer is downloaded and a Sqlite database generated.
+    Once installed, you can search the database:
 
-Usage
------
+    .. code:: bash
 
-Once installed, you can search the database::
+        $ when --db-search New York
+        5106292, West New York, West New York, US, New Jersey, America/New_York
+        5128581, New York City, New York City, US, New York, America/New_York
 
-    $ when --db-search New York
-    5106292, West New York, West New York, US, New Jersey, America/New_York
-    5128581, New York City, New York City, US, New York, America/New_York
+* Aliases: ``--db-alias``
 
+    You can add aliases for easier search. In the example directly above, we see that New York City has
+    a GeoNames ID of 5128581. Pass that to the ``--db-alias`` option along with another name that
+    you would like to use:
 
-Additionally, you can add aliases. In the example directly above, we see that New York City has
-a GeoNames ID of 5128581. Pass that to the ``--db-alias`` option along with another name that
-you would like to use::
+    .. code:: bash
 
-    $ when --db-alias 5128581 NYC
-    $ when --source NYC
-    2023-07-06 07:58:33-0400 (EDT, America/New_York) 187d27w (New York City, New York, US)[🌕 Full Moon]
+        $ when --db-alias 5128581 NYC
+        $ when --source NYC
+        2023-07-06 07:58:33-0400 (EDT, America/New_York) 187d27w (New York City, New York, US)[🌕 Full Moon]
 
+* Alias listing: ``--db-aliases``
 
-Example
--------
+
+Examples
+========
 
 For the sake of clarity, in the following examples I am in Seoul, Korea.
 
@@ -101,24 +151,100 @@ For the sake of clarity, in the following examples I am in Seoul, Korea.
     1945-03-07 22:00:00-0400 (EWT, America/New_York) 066d10w [🌘 Waning Crescent]
 
 
-Develop
--------
+Development
+===========
 
-Requirements Python 3.10+. Also, [just](https://github.com/casey/just) for convenience.
+Requires Python 3.10+ and just_ for convenience.
 
 .. code:: bash
 
     $ git clone [email protected]:dakrauth/when.git
     $ cd when
-    $ just
-    $ just venv
+    $ just  # or just help
+
+Set up dev env:
+
+.. code:: bash
+
+    $ just init
+
+Test, and code coverage:
+
+.. code:: bash
+
     $ just test
+    $ just cov
+
+Only run a test matching matching a given substring:
+
+.. code:: bash
+
+    $ just test -k test_sometest
+
+Interactive development:
+
+.. code:: bash
+
     $ . ./venv/bin/activate
     $ when --help
     $ when --db
 
 Further Reading
----------------
+===============
+
+`Time Zones Aren’t Offsets – Offsets Aren’t Time Zones`_
+
+.. _pipx: https://pypa.github.io/pipx/
+.. _just: https://github.com/casey/just
+.. _`Time Zones Aren’t Offsets – Offsets Aren’t Time Zones`: https://spin.atomicobject.com/time-zones-offsets/)
+.. _GeoNames: https://www.geonames.org/export/
+
+Complete Usage
+==============
+
+.. code:: bash
+
+    usage: when [--delta {long,short}] [--offset [+-]?(\d+wdhm)+] [-h] [--prefix] [-s SOURCE] [-t TARGET] [-f FORMAT] [-g] [--all]
+                [--holidays COUNTRY_CODE] [-v] [-V] [--json] [--config] [--db] [--db-force] [--db-search] [--exact] [--db-alias DB_ALIAS]
+                [--db-aliases] [--db-size DB_SIZE] [--db-pop DB_POP] [--tz-alias] [--fullmoon]
+                [timestr ...]
+
+    Convert times to and from time zones or cities
+
+    positional arguments:
+      timestr               Timestamp to parse, defaults to local time
+
+    options:
+      --delta {long,short}  Show the delta to the given timestamp
+      --offset [+-]?(\d+wdhm)+
+                            Show the difference from a given offset
+      -h, --help            Show helpful usage information
+      --prefix              Show when's directory
+      -s SOURCE, --source SOURCE
+                            Timezone / city to convert the timestr from, defaulting to local time
+      -t TARGET, --target TARGET
+                            Timezone / city to convert the timestr to (globbing patterns allowed, can be comma delimited), defaulting to local
+                            time
+      -f FORMAT, --format FORMAT
+                            Output formatting. Additional formats can be shown using the -v option with -h
+      -g, --group           Group sources together under same target results
+      --all                 Show times in all common timezones
+      --holidays COUNTRY_CODE
+                            Show holidays for given country code.
+      -v, --verbosity       Verbosity (-v, -vv, etc). Use -v to show `when` extension detailed help
+      -V, --version         show program's version number and exit
+      --json                Output results in nicely formatted JSON
+      --config              Toggle config mode. With no other option, dump current configuration settings
+      --db                  Create cities database, used with --db-size and --db-pop
+      --db-force            Force an existing database to be overwritten
+      --db-search           Search database for the given city
+      --exact               DB searches must be exact
+      --db-alias DB_ALIAS   Create a new alias from the city id
+      --db-aliases          Show all DB aliases
+      --db-size DB_SIZE     Geonames file size. Can be one of 'xl' ('xlarge'), 'lg' ('large'), 'md' ('medium'), 'sm' ('small').
+      --db-pop DB_POP       City population minimum.
+      --tz-alias            Search for a time zone alias
+      --fullmoon            Show full moon(s) for given year or month. Can be in the format of: 'next' | 'prev' | YYYY[-MM]
+
+    Use -v option for details
 
-[Time Zones Aren’t Offsets – Offsets Aren’t Time Zones
-](https://spin.atomicobject.com/time-zones-offsets/)
diff --git a/src/when/cli.py b/src/when/cli.py
@@ -1,15 +1,13 @@
 #!/usr/bin/env python
 import argparse
-import logging
 import sys
+import logging
 from pathlib import Path
 
 from . import __version__, core, db, utils, lunar, exceptions
 from . import timezones
 from .config import Settings, __doc__ as FORMAT_HELP
 
-logger = logging.getLogger(__name__)
-
 
 def get_parser(settings):
     class DBSizeAction(argparse.Action):
@@ -227,11 +225,14 @@ def log_config(verbosity, settings):
             logging.getLogger("asyncio").setLevel(logging.WARNING)
 
     logging.basicConfig(level=log_level, format=log_format, force=True)
+    logger = utils.logger()
     logger.debug(
         "Configuration files read: %s",
         ", ".join(str(s) for s in settings.read_from) if settings.read_from else "None",
     )
 
+    return logger
+
 
 def main(sys_args, when=None, settings=None):
     if "--pdb" in sys_args:  # pragma: no cover
@@ -258,7 +259,7 @@ def main(sys_args, when=None, settings=None):
     parser = get_parser(settings)
     args = parser.parse_args(sys_args)
 
-    log_config(args.verbosity, settings)
+    logger = log_config(args.verbosity, settings)
     logger.debug(args)
     if args.help:
         parser.print_help()

diff --git a/src/when/core.py b/src/when/core.py
@@ -13,7 +13,7 @@
 from .db import client
 from .lunar import lunar_phase
 
-logger = logging.getLogger(__name__)
+logger = utils.logger()
 
 
 def holidays(settings, co="US", ts=None):