Merge pull request #127 from kaijensen55/docs/docstrings-standardization

docs: standardize docstrings (Google) + Ruff/napoleon config

Author: alpha-xone

.pre-commit-config.yaml

@@ -0,0 +1,9 @@
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.14.3
+    hooks:
+      - id: ruff-check
+        args: [ --fix ]
+      - id: ruff-format
+
+

Examples.ipynb

@@ -1,4 +1,3 @@
-# -*- coding: utf-8 -*-
 #
 # Configuration file for the Sphinx documentation builder.
 #
@@ -24,7 +23,7 @@
 def parse_version(package):
 
     init_file = '%s/%s/__init__.py' % (ROOT_PATH, package)
-    with open(init_file, 'r', encoding='utf-8') as f:
+    with open(init_file, encoding='utf-8') as f:
         for line in f.readlines():
             if '__version__' in line:
                 return line.split('=')[1].strip()[1:-1]
@@ -53,12 +52,14 @@ def parse_version(package):
 # ones.
 extensions = [
     'sphinx.ext.autodoc',
+    'sphinx.ext.autosummary',
     'sphinx.ext.todo',
     'sphinx.ext.coverage',
     'sphinx.ext.mathjax',
     'sphinx.ext.ifconfig',
     'sphinx.ext.viewcode',
     'sphinx.ext.githubpages',
+    'sphinx.ext.napoleon',
     'sphinx_llms_txt',
     # 'IPython.sphinxext.ipython_console_highlighting',
     # 'IPython.sphinxext.ipython_directive',
@@ -192,3 +193,19 @@ def parse_version(package):
 epub_exclude_files = ['search.html']
 
 # -- Extension configuration -------------------------------------------------
+
+# Configure napoleon to parse Google-style docstrings
+napoleon_google_docstring = True
+napoleon_numpy_docstring = False
+napoleon_include_init_with_doc = False
+napoleon_preprocess_types = True
+
+# Autodoc / autosummary configuration
+autosummary_generate = True
+autodoc_typehints = 'description'
+autodoc_default_options = {
+    'members': True,
+    'undoc-members': False,
+    'inherited-members': True,
+    'show-inheritance': True,
+}

docs/conf.py

@@ -0,0 +1,18 @@
+Docstring Standardization
+=========================
+
+Style
+-----
+
+- Preferred style: `Google Python Style Guide (Docstrings) <https://google.github.io/styleguide/pyguide.html#38-comments-and-docstrings>`_.
+- Rendered via Sphinx with ``sphinx.ext.napoleon`` (Google-style parsing enabled).
+
+Guidelines
+----------
+
+- Include a short summary line in the imperative mood.
+- Provide sections as needed: ``Args``, ``Returns``, ``Yields``, ``Raises``, ``Notes``, ``Examples``.
+- Use explicit types and shapes when helpful; prefer concrete meanings over abbreviations.
+- Keep examples runnable when possible.
+
+

docs/docstring_style.rst

@@ -55,18 +55,10 @@ Supported Python versions: 3.7 – 3.14 (universal wheel)
 What's New
 ==========
 
-*Unreleased*
-
 .. xbbg:changelog-start
 
 .. xbbg:changelog-end
 
-- Improve date parsing and stability in ``pipeline.format_raw`` (coerce datetime columns by name)
-- Normalize numeric types in ``const.ccy_pair`` to ensure stable representations
-- Fix ``core.utils.fstr``/``to_str`` formatting with explicit kwargs
-- Add docs build to CI and modernize CI matrix (Windows/Linux)
-- Switch to PyPI Trusted Publishing (OIDC)
-
 *0.7.7a2* - Custom `config` and etc. for reference exchange (author `hceh`)
 
 *0.7.6a2* - Use `blp.connect` for alternative Bloomberg connection (author `anxl2008`)
@@ -89,6 +81,14 @@ in ``/xbbg/markets/exch.yml``). See example of ``bdib`` below for more details.
 
 *0.1.17* - Add ``adjust`` argument in ``bdh`` for easier dividend / split adjustments
 
+Contents
+========
+
+.. toctree::
+   :maxdepth: 1
+
+   docstring_style
+
 Tutorial
 ========
 

docs/index.rst

@@ -1,10 +1,11 @@
-import pynng
-import trio
+from functools import partial
+
 import fire
 import orjson
+import pynng
+import trio
 
 from xbbg import blp
-from functools import partial
 
 DEFAULT_FDLS = [
     'MKTDATA_EVENT_TYPE', 'EVT_TRADE_DATE_RT', 'TIME',
@@ -16,8 +17,7 @@
 
 
 async def live(channel: str, tickers, **kwargs):
-    """
-    Broadcasts live data feeds
+    """Broadcasts live data feeds
 
     Args:
         channel: channel name

feeds/pub.py

@@ -1,8 +1,8 @@
+from functools import partial
+
+import fire
 import pynng
 import trio
-import fire
-
-from functools import partial
 
 ADDRESS = 'ipc:///xbbg/stream'
 

feeds/sub.py

@@ -35,7 +35,7 @@ dependencies = [
 # Kept for compatibility if consumers expect extras, but dev/test tooling
 # is managed via uv dependency groups below.
 test = ["pytest", "pytest-cov", "coverage", "codecov"]
-dev = ["ruff", "ipykernel", "build", "twine"]
+dev = ["ruff", "ipykernel", "build", "twine", "pre-commit"]
 docs = ["sphinx>=5.3.0", "sphinx-rtd-theme>=2.0.0", "sphinx-llms-txt>=0.7.0"]
 
 [project.urls]
@@ -70,7 +70,10 @@ target-version = "py310"
 line-length = 120
 exclude = [
   "xbbg/feeds/*",
+  "feeds/**",
   "docs/_build",
+  "docs/conf.py",
+  "Examples.ipynb",
   "dist",
   "venv",
   ".venv",
@@ -82,6 +85,7 @@ select = [
   "W",   # pycodestyle warnings
   "F",   # pyflakes
   "I",   # isort
+  "D",   # pydocstyle
   "UP",  # pyupgrade
   "B",   # flake8-bugbear
   "C4",  # flake8-comprehensions
@@ -92,11 +96,14 @@ select = [
 ignore = [
   "E701", # multiple statements on one line (colon)
   "E501", # line too long
+  "D104", # Missing docstring in public package
+  "D107", # Missing docstring in __init__
 ]
 
 [tool.ruff.lint.per-file-ignores]
 "xbbg/__init__.py" = ["F401"]
 "xbbg/**/__init__.py" = ["F401"]
+"xbbg/tests/**" = ["D"]
 
 [tool.ruff.lint.isort]
 known-first-party = ["xbbg"]
@@ -106,6 +113,9 @@ force-sort-within-sections = true
 [tool.ruff.lint.mccabe]
 max-complexity = 12
 
+[tool.ruff.lint.pydocstyle]
+convention = "google"
+