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
+
+   <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 %}
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
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/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)
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 "<sstream>" namespace "std":
     cdef cppclass stringstream: