+
diff --git a/docs/conf.py b/docs/conf.py
index df6a746..cb7e1fb 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -4,7 +4,7 @@
from datetime import datetime
# Insert the parent directory into the path
-sys.path.insert(0, os.path.abspath("../reuters_style"))
+sys.path.insert(0, os.path.abspath("../"))
project = "reuters-style"
year = datetime.now().year
@@ -14,9 +14,22 @@
templates_path = ["_templates"]
exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
-html_theme = "sphinx_rtd_theme"
+html_theme = "alabaster"
html_baseurl = "/docs/"
pygments_style = "sphinx"
+html_sidebars = {
+ "**": [
+ # "about.html",
+ # "navigation.html",
+ "relations.html",
+ "searchbox.html",
+ ]
+}
+
+html_static_path = ["_static"]
+html_css_files = [
+ "css/custom.css",
+]
autodoc_member_order = "bysource"
autodoc_default_options = {
@@ -26,6 +39,7 @@
"undoc-members": True,
"show-inheritance": True,
}
+autodoc_mock_imports = ["pytz"]
extensions = [
"myst_parser",
diff --git a/docs/index.md b/docs/index.md
index e3925c6..d025f5d 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -1,3 +1,22 @@
-# Your package name
+```{include} _templates/nav.html
+```
-Your documention starts here ...
+# reuters-style
+
+Format dates, numbers and text to conform with the Reuters Style Guide, the standards that guide the world's largest independent newsroom
+
+## Installation
+
+Install the package from the Python Package Index (PyPI) with pipenv:
+
+```bash
+pipenv install reuters-style
+```
+
+## Usage
+
+The library currently features the following methods:
+
+```{eval-rst}
+.. automodule:: reuters_style
+```
diff --git a/reuters_style/__init__.py b/reuters_style/__init__.py
index 1abeed0..39b764e 100644
--- a/reuters_style/__init__.py
+++ b/reuters_style/__init__.py
@@ -1,41 +1,27 @@
-"""Format dates, numbers and text to conform with the Reuters Style Guide, the standards that guide the world's largest independent newsroom."""
from __future__ import annotations
from datetime import datetime, timezone
-def dayofweek(dt: datetime, tabular: bool = False) -> str:
- """Format the day of the week according to Reuters style.
+def date(dt: datetime) -> str:
+ """Format a date according to Reuters style.
- Args:
- dt: The datetime to format. (datetime)
- tabular: Whether to format the day of the week for a tabular display. (bool)
+ In text, use the sequence month/day/year, e.g., “Iraq’s invasion of Kuwait on
+ Aug. 2, 1990, led to...” or “the Aug. 2 invasion” or “the August 1990 invasion.”
- Returns:
- The formatted day of the week. (str)
+ If a specific date is used, put the year inside commas. Spell out months
+ in text, but abbreviate them followed by a full stop when they are used
+ with a specific date – Jan.1.
- Example:
- >>> import reuters_style
- >>> reuters_style.dayofweek(datetime(2021, 9, 1))
- 'Wednesday'
- """
- if tabular:
- days = ["Mon", "Tue", "Wed", "Thu", "Fri", "Sat", "Sun"]
- else:
- days = [
- "Monday",
- "Tuesday",
- "Wednesday",
- "Thursday",
- "Friday",
- "Saturday",
- "Sunday",
- ]
- return days[dt.weekday()]
+ When spelling out duration, write, “The tournament runs from May 22 to 24,”
+ not “…runs from May 22-24.” Write “arrived on Monday,” not “arrived Monday”
+ and “on Tuesday,” rather than “yesterday,” “today,” “tomorrow.” Write
+ “the 1939-45 war” but “from 1939 to 1945,” not “from 1939-45.” Write 9/11,
+ not 9-11. In commodities stories, write “Brazil’s 2013/14 soybean crop”
+ (conventional use), not “2013-14.”
-
-def date(dt: datetime) -> str:
- """Format a date according to Reuters style.
+ Abbreviate as follows, noting the dot after the abbreviation: Jan., Feb.,
+ March, April, May, June, July, Aug., Sept., Oct., Nov., Dec.
Args:
dt: The datetime to format. (datetime)
@@ -67,9 +53,63 @@ def date(dt: datetime) -> str:
return f"{months[dt.month - 1]} {dt.strftime('%-d')}, {dt.strftime('%Y')}"
+def dayofweek(dt: datetime, tabular: bool = False) -> str:
+ """Format the day of the week according to Reuters style.
+
+ Always precede the day of the week with the word "on" as in she said on Monday,
+ not she said Monday. Do not abbreviate the days of the week, except in a
+ tabular format: Sun, Mon, Tue, Wed, Thu, Fri, Sat (three letters, without periods).
+
+ Args:
+ dt: The datetime to format. (datetime)
+ tabular: Whether to format the day of the week for a tabular display. (bool)
+
+ Returns:
+ The formatted day of the week. (str)
+
+ Example:
+ >>> import reuters_style
+ >>> reuters_style.dayofweek(datetime(2021, 9, 1))
+ 'Wednesday'
+ >>> reuters_style.dayofweek(datetime(2021, 9, 1), tabular=True)
+ 'Wed'
+ """
+ if tabular:
+ days = ["Mon", "Tue", "Wed", "Thu", "Fri", "Sat", "Sun"]
+ else:
+ days = [
+ "Monday",
+ "Tuesday",
+ "Wednesday",
+ "Thursday",
+ "Friday",
+ "Saturday",
+ "Sunday",
+ ]
+ return days[dt.weekday()]
+
+
def time(dt: datetime, include_timezone: bool = True) -> str:
"""Format a time according to Reuters style.
+ Abbreviations of time zones are acceptable providing the GMT equivalent is given.
+ BST (British Summer Time) = GMT +1 CET (Central European Time) = GMT +1 CDT
+ (Central Daylight Time) = GMT -5 CST (Central Standard Time) = GMT -6 EST
+ (Eastern Standard Time) = GMT -5 MDT (Mountain Daylight Time) = GMT -6 MST
+ (Mountain Standard Time) = GMT -7 PST (Pacific Standard Time) = GMT -8.and
+
+ When referring to times, first give the local time by the 12-hour clock (without
+ using the words local time) and follow it with a bracketed conversion to a
+ 24-hour clock time for a specified time zone, e.g., “will meet at 10 a.m.
+ (1600 GMT).”
+
+ Use figures except for noon and midnight. Use a colon to separate
+ hours and minutes, e.g., 3:15 p.m. Use the style “on Friday,” “on Saturday,”
+ rather than the looser “today,” “yesterday,” “tomorrow.”
+
+ Do not use phrases like “several months ago” or “recently,” which suggest we do not know when something
+ happened or are too lazy to find out. Be precise – “last August” or “on Feb. 2.”
+
Args:
dt: The datetime to format. (datetime)
include_timezone: Whether to include the timezone in the result. (bool)
@@ -87,6 +127,7 @@ def time(dt: datetime, include_timezone: bool = True) -> str:
'12:30 p.m. GMT'
>>> reuters_style.time(datetime(2021, 9, 1, 12, 30), include_timezone=False)
'12:30 p.m.'
+ >>> import pytz
>>> tz = pytz.timezone('Africa/Johannesburg')
>>> reuters_style.time(tz.localize(datetime(2021, 9, 1, 12, 30)))
'12:30 p.m. SAST'