Doc tweaks

docs/source/_templates/autosummary/class.rst

@@ -0,0 +1,44 @@
+.. raw:: html
+
+   <div class="prename">{{ module }}.</div>
+   <div class="empty"></div>
+
+{{ 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 %}

docs/source/_templates/custom-module-template.rst → 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 %}

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

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

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())

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

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
 
 
 

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
 
     """
 

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(

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

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