From e3492de5374f5b7bd376abbbfa1b36c6586d60f4 Mon Sep 17 00:00:00 2001 From: Guillaume Horel Date: Wed, 13 Aug 2025 12:16:54 -0400 Subject: [PATCH 1/3] doc tweaks --- docs/source/_templates/autosummary/class.rst | 44 +++++++++++++++++++ .../module.rst} | 32 ++++++-------- .../_templates/custom-class-template.rst | 36 --------------- docs/source/api.rst | 1 - docs/source/conf.py | 9 ++-- 5 files changed, 62 insertions(+), 60 deletions(-) create mode 100644 docs/source/_templates/autosummary/class.rst rename docs/source/_templates/{custom-module-template.rst => autosummary/module.rst} (67%) delete mode 100644 docs/source/_templates/custom-class-template.rst diff --git a/docs/source/_templates/autosummary/class.rst b/docs/source/_templates/autosummary/class.rst new file mode 100644 index 000000000..21bc9abb6 --- /dev/null +++ b/docs/source/_templates/autosummary/class.rst @@ -0,0 +1,44 @@ +.. raw:: html + +
{{ module }}.
+
+ +{{ name }} +{{ underline }} + +.. currentmodule:: {{ module }} + +.. autoclass:: {{ objname }} + :show-inheritance: + :no-members: + :no-inherited-members: + :no-special-members: + + {% block methods %} + .. HACK -- the point here is that we don't want this to appear in the output, but the autosummary should still generate the pages. + .. autosummary:: + :toctree: + {% for item in all_methods %} + {%- if not item.startswith('_') or item in ['__call__', '__mul__', '__getitem__', '__len__', '__pow__'] %} + {{ name }}.{{ item }} + {%- endif -%} + {%- endfor %} + {% for item in inherited_members %} + {%- if item in ['__call__', '__mul__', '__getitem__', '__len__', '__pow__'] %} + {{ name }}.{{ item }} + {%- endif -%} + {%- endfor %} + {% endblock %} + + {% block attributes %} + {% if attributes %} + .. HACK -- the point here is that we don't want this to appear in the output, but the autosummary should still generate the pages. + .. autosummary:: + :toctree: + {% for item in all_attributes %} + {%- if not item.startswith('_') %} + {{ name }}.{{ item }} + {%- endif -%} + {%- endfor %} + {% endif %} + {% endblock %} diff --git a/docs/source/_templates/custom-module-template.rst b/docs/source/_templates/autosummary/module.rst similarity index 67% rename from docs/source/_templates/custom-module-template.rst rename to docs/source/_templates/autosummary/module.rst index f46f9f63e..61f038606 100644 --- a/docs/source/_templates/custom-module-template.rst +++ b/docs/source/_templates/autosummary/module.rst @@ -3,7 +3,7 @@ .. automodule:: {{ fullname }} {% block attributes %} - {% if attributes %} + {%- if attributes %} .. rubric:: {{ _('Module Attributes') }} .. autosummary:: @@ -12,55 +12,51 @@ {{ item }} {%- endfor %} {% endif %} - {% endblock %} + {%- endblock %} - {% block functions %} - {% if functions %} + {%- block functions %} + {%- if functions %} .. rubric:: {{ _('Functions') }} .. autosummary:: - :toctree: {% for item in functions %} {{ item }} {%- endfor %} {% endif %} - {% endblock %} + {%- endblock %} - {% block classes %} - {% if classes %} + {%- block classes %} + {%- if classes %} .. rubric:: {{ _('Classes') }} .. autosummary:: :toctree: - :template: custom-class-template.rst {% for item in classes %} {{ item }} {%- endfor %} {% endif %} - {% endblock %} + {%- endblock %} - {% block exceptions %} - {% if exceptions %} + {%- block exceptions %} + {%- if exceptions %} .. rubric:: {{ _('Exceptions') }} .. autosummary:: - :toctree: {% for item in exceptions %} {{ item }} {%- endfor %} {% endif %} - {% endblock %} + {%- endblock %} -{% block modules %} -{% if modules %} +{%- block modules %} +{%- if modules %} .. rubric:: Modules .. autosummary:: :toctree: - :template: custom-module-template.rst :recursive: {% for item in modules %} {{ item }} {%- endfor %} {% endif %} -{% endblock %} +{%- endblock %} diff --git a/docs/source/_templates/custom-class-template.rst b/docs/source/_templates/custom-class-template.rst deleted file mode 100644 index 9168c1cb8..000000000 --- a/docs/source/_templates/custom-class-template.rst +++ /dev/null @@ -1,36 +0,0 @@ -{{ fullname | escape | underline}} - -.. currentmodule:: {{ module }} - -.. autoclass:: {{ objname }} - :members: - :show-inheritance: - - {% block methods %} - .. automethod:: __init__ - - {% if methods %} - .. rubric:: {{ _('Methods') }} - - .. autosummary:: - - - {% for item in methods %} - ~{{ name }}.{{ item }} - - {%- endfor %} - {% endif %} - {% endblock %} - - {% block attributes %} - {% if attributes %} - .. rubric:: {{ _('Attributes') }} - - .. autosummary:: - - {% for item in attributes %} - ~{{ name }}.{{ item }} - {%- endfor %} - - {% endif %} - {% endblock %} diff --git a/docs/source/api.rst b/docs/source/api.rst index dcc85d460..89ce13b98 100644 --- a/docs/source/api.rst +++ b/docs/source/api.rst @@ -8,7 +8,6 @@ are completely hidden being the Python layers (for example ``std::shared_ptr`` a .. autosummary:: :toctree: _autosummary - :template: custom-module-template.rst :recursive: quantlib diff --git a/docs/source/conf.py b/docs/source/conf.py index 30ef0b116..a3f697a3c 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -25,13 +25,12 @@ # Add any Sphinx extension module names here, as strings. They can be extensions # coming with Sphinx (named 'sphinx.ext.*') or your custom ones. -extensions = ['sphinx.ext.autodoc', 'sphinx.ext.autosummary', - 'sphinx.ext.imgmath', 'sphinx.ext.napoleon', 'nbsphinx'] +extensions = ['sphinx.ext.autodoc', 'numpydoc', + 'sphinx.ext.imgmath', 'nbsphinx'] nbsphinx_execute_arguments = [ "--InlineBackend.figure_formats={'svg', 'pdf'}", "--InlineBackend.rc=figure.dpi=96", ] -napoleon_use_param = True autosummary_generate = True # Add any paths that contain templates here, relative to this directory. templates_path = ['_templates'] @@ -47,8 +46,8 @@ master_doc = 'index' # General information about the project. -project = u'Quantlib cython wrapper' -copyright = u'2011, Didrik Pinte, Patrick Henaff' +project = 'Quantlib cython wrapper' +copyright = '2011, Didrik Pinte, Patrick Henaff' # The version info for the project you're documenting, acts as replacement for # |version| and |release|, also used in various other places throughout the From ecf00fd54afdc930afc36cf975cd5f49cb16efbc Mon Sep 17 00:00:00 2001 From: Guillaume Horel Date: Wed, 13 Aug 2025 13:02:52 -0400 Subject: [PATCH 2/3] improve docstrings --- quantlib/time/calendar.pyx | 7 +++-- quantlib/time/calendars/united_states.pxd | 36 +++++++++++++++++------ quantlib/time/calendars/united_states.pyx | 36 ++++++++++++++++++----- 3 files changed, 60 insertions(+), 19 deletions(-) diff --git a/quantlib/time/calendar.pyx b/quantlib/time/calendar.pyx index 4bb2cd2df..ea3a6fa21 100644 --- a/quantlib/time/calendar.pyx +++ b/quantlib/time/calendar.pyx @@ -27,9 +27,10 @@ cdef class Calendar: calendars will be moved to the exchange/country convention. ''' - property name: - def __get__(self): - return self._thisptr.name().decode('utf-8') + @property + def name(self): + """name of the calendar""" + return self._thisptr.name().decode('utf-8') def __str__(self): return self.name diff --git a/quantlib/time/calendars/united_states.pxd b/quantlib/time/calendars/united_states.pxd index bfedfc306..45898e9e5 100644 --- a/quantlib/time/calendars/united_states.pxd +++ b/quantlib/time/calendars/united_states.pxd @@ -1,12 +1,30 @@ cdef extern from 'ql/time/calendars/unitedstates.hpp' namespace \ -'QuantLib::UnitedStates': +'QuantLib::UnitedStates' nogil: cpdef enum class Market: - """ US calendars""" - Settlement # generic settlement calendar - NYSE # New York stock exchange calendar - GovernmentBond # government-bond calendar - NERC # off-peak days for NERC - LiborImpact # Libor impact calendar - FederalReserve # Federal Reserve Bankwire System - SOFR # SOFR fixing calendar + """ US calendars + + Attributes + ---------- + Settlement + generic settlement calendar + NYSE + New York stock exchange calendar + GovernmentBond + government-bond calendar + NERC + off-peak days for NERC + LiborImpact + Libor impact calendar + FederalReserve + Federal Reserve Bankwire System + SOFR + SOFR fixing calendar + """ + Settlement + NYSE + GovernmentBond + NERC + LiborImpact + FederalReserve + SOFR diff --git a/quantlib/time/calendars/united_states.pyx b/quantlib/time/calendars/united_states.pyx index 34d4f3725..a59e00cc8 100644 --- a/quantlib/time/calendars/united_states.pyx +++ b/quantlib/time/calendars/united_states.pyx @@ -74,15 +74,37 @@ cdef class UnitedStates(Calendar): * Labor Day, first Monday in September * Thanksgiving Day, fourth Thursday in November * Christmas, December 25th (moved to Monday if Sunday) + + Parameters + ---------- + market: Market, default Market.Settlement + + Attributes + ---------- + Settlement + generic settlement calendar + NYSE + New York stock exchange calendar + GovernmentBond + government-bond calendar + NERC + off-peak days for NERC + LiborImpact + Libor impact + FederalReserve + Federal Reserve Bankwire System + SOFR + SOFR fixing calendar + ''' - Settlement = Market.Settlement # generic settlement calendar - NYSE = Market.NYSE # New York stock exchange calendar - GovernmentBond = Market.GovernmentBond # government-bond calendar - NERC = Market.NERC # off-peak days for NERC - LiborImpact = Market.LiborImpact # Libor impact - FederalReserve = Market.FederalReserve # Federal Reserve Bankwire System - SOFR = Market.SOFR # SOFR fixing calendar + Settlement = Market.Settlement + NYSE = Market.NYSE + GovernmentBond = Market.GovernmentBond + NERC = Market.NERC + LiborImpact = Market.LiborImpact + FederalReserve = Market.FederalReserve + SOFR = Market.SOFR def __cinit__(self, Market market=Market.Settlement): self._thisptr = _us.UnitedStates(market) From de2e7fcdffbb96f260eaf7ebbf6d32186a0f4785 Mon Sep 17 00:00:00 2001 From: Guillaume Horel Date: Thu, 14 Aug 2025 08:24:54 -0400 Subject: [PATCH 3/3] better docstrings --- quantlib/instrument.pyx | 9 ++- quantlib/instruments/bond.pyx | 2 +- quantlib/option.pxd | 12 +++- .../replicating_variance_swap_engine.pyx | 25 ++++---- .../volatility/equityfx/local_vol_surface.pyx | 16 ++++-- quantlib/time/frequency.pxd | 57 ++++++++++++++----- 6 files changed, 87 insertions(+), 34 deletions(-) diff --git a/quantlib/instrument.pyx b/quantlib/instrument.pyx index a09c088c1..1dbf082b2 100644 --- a/quantlib/instrument.pyx +++ b/quantlib/instrument.pyx @@ -31,9 +31,16 @@ cdef class Instrument(Observable): return self._thisptr.get().NPV() @property - def is_expired(self): + def is_expired(self) -> bool: + """whether the instrument might ave value greater than zero.""" return self._thisptr.get().isExpired() @property def valuation_date(self): + """the date the net present value refers to. + + Returns + ------- + valuation_date: :class:`~quantlib.time.date.Date` + """ return date_from_qldate(self._thisptr.get().valuationDate()) diff --git a/quantlib/instruments/bond.pyx b/quantlib/instruments/bond.pyx index 442fc2c7f..ce581d5cc 100644 --- a/quantlib/instruments/bond.pyx +++ b/quantlib/instruments/bond.pyx @@ -109,7 +109,7 @@ cdef class Bond(Instrument): @property def cashflows(self): - """ cash flow stream as a Leg """ + """ cash flow stream as a :class:`~quantlib.cashflow.Leg`.""" cdef Leg leg = Leg.__new__(Leg) leg._thisptr = self.as_ptr().cashflows() return leg diff --git a/quantlib/option.pxd b/quantlib/option.pxd index 583ab2f53..2240b5464 100644 --- a/quantlib/option.pxd +++ b/quantlib/option.pxd @@ -1,9 +1,15 @@ from quantlib.instrument cimport Instrument -cdef extern from 'ql/option.hpp' namespace 'QuantLib::Option': +cdef extern from 'ql/option.hpp' namespace 'QuantLib::Option' nogil: cpdef enum class OptionType "QuantLib::Option::Type": - Put - Call + """ + Attributes + ---------- + Put + Call + """ + Put + Call diff --git a/quantlib/pricingengines/forward/replicating_variance_swap_engine.pyx b/quantlib/pricingengines/forward/replicating_variance_swap_engine.pyx index 7c1d1cbfe..a2f6eda13 100644 --- a/quantlib/pricingengines/forward/replicating_variance_swap_engine.pyx +++ b/quantlib/pricingengines/forward/replicating_variance_swap_engine.pyx @@ -9,19 +9,20 @@ from quantlib.pricingengines.engine cimport PricingEngine from ._replicating_variance_swap_engine cimport ReplicatingVarianceSwapEngine as _ReplicatingVarianceSwapEngine cdef class ReplicatingVarianceSwapEngine(PricingEngine): - """ - Variance-swap pricing engine using replicating cost, - as described in Demeterfi, Derman, Kamal & Zou, - "A Guide to Volatility and Variance Swaps", 1999 - - Attributes - --------- - process : :obj:`GeneralizedBlackScholesProcess` - call_strikes : list of :obj:`Real` - put_strikes : list of :obj:`Real` - dk : Real - 5.0 + """Variance-swap pricing engine using replicating cost + + as described in [1]_. + + Parameters + ---------- + process : :class:`~quantlib.processes.black_scholes_process.GeneralizedBlackScholesProcess` + call_strikes : list of :obj:`Real` + put_strikes : list of :obj:`Real` + dk : Real, default 5.0 + References + ---------- + .. [1] Demeterfi, Derman, Kamal & Zou, "A Guide to Volatility and Variance Swaps", 1999 """ diff --git a/quantlib/termstructures/volatility/equityfx/local_vol_surface.pyx b/quantlib/termstructures/volatility/equityfx/local_vol_surface.pyx index df91f643d..70ba37fa8 100644 --- a/quantlib/termstructures/volatility/equityfx/local_vol_surface.pyx +++ b/quantlib/termstructures/volatility/equityfx/local_vol_surface.pyx @@ -13,15 +13,23 @@ cdef class LocalVolSurface(LocalVolTermStructure): def __init__(self, BlackVolTermStructure black_ts, HandleYieldTermStructure risk_free_ts, HandleYieldTermStructure dividend_ts, Quote underlying): """ Local volatility surface derived from a Black vol surface - For details about this implementation refer to [Gat]_. - Parameters ---------- black_ts : BlackVolTermStructure risk_free_ts : YieldTermStructure - dividend_ts : YieldTermStructure, the dividend term structure. - underlying : Quote, the spot underlying + dividend_ts : YieldTermStructure + the dividend term structure. + underlying : Quote + the spot underlying. + + Notes + ----- + For details about this implementation refer to [Gat]_. + + + References + ---------- .. [Gat] "Stochastic Volatility and LocalVolatility" in *Case Studies and Financial Modelling Course Notes,* Jim Gatheral, Fall Term, 2003 https://web.math.ku.dk/~rolf/teaching/ctff03/Gatheral.1.pdf """ self._thisptr.reset( diff --git a/quantlib/time/frequency.pxd b/quantlib/time/frequency.pxd index 7048c8fff..f1e004a31 100644 --- a/quantlib/time/frequency.pxd +++ b/quantlib/time/frequency.pxd @@ -2,19 +2,50 @@ from libcpp.string cimport string cdef extern from 'ql/time/frequency.hpp' namespace "QuantLib" nogil: cpdef enum Frequency: - NoFrequency = -1 # null frequency - Once = 0 # only once, e.g., a zero-coupon - Annual = 1 # once a year - Semiannual = 2 # twice a year - EveryFourthMonth = 3 # every fourth month - Quarterly = 4 # every third month - Bimonthly = 6 # every second month - Monthly = 12 # once a month - EveryFourthWeek = 13 # every fourth week - Biweekly = 26 # every second week - Weekly = 52 # once a week - Daily = 365 # once a day - OtherFrequency = 999 # some other unknown frequency + """Frequency of events + + Attributes + ---------- + NoFrequency + null frequency + Once + only once, e.g., a zero-coupon + Annual + once a year + Semiannual + twice a year + EveryFourthMonth + every fourth month + Quarterly + every third month + Bimonthly + every second month + Monthly + once a month + EveryFourthWeek + every fourth week + Biweekly + every second week + Weekly + once a week + Daily + once a day + OtherFrequency + some other unknown frequency + """ + NoFrequency + Once + Annual + Semiannual + EveryFourthMonth + Quarterly + Bimonthly + Monthly + EveryFourthWeek + Biweekly + Weekly + Daily + OtherFrequency cdef extern from "" namespace "std": cdef cppclass stringstream: