refactoring of dnssec documentation

- replaces old comments with sphinx style comments
- adds support for sphinx.ext.todo
- since `_validate()` and `_validate_rrsig()` are only internal functions they are removed from documentation

diff --git a/dns/dnssec.py b/dns/dnssec.py
index de69de8744d8b0f160c1a09ecf98e897dec91b23..1abab9417f00d378fd67ef2c3acc9ade143cd54d 100644 (file)
--- a/dns/dnssec.py
+++ b/dns/dnssec.py
@@ -95,7 +95,10 @@ _algorithm_by_value = {y: x for x, y in _algorithm_by_text.items()}
 def algorithm_from_text(text):
     """Convert text into a DNSSEC algorithm value.
 
-    Returns an ``int``.
+    :param text: text to convert to value
+    :type text: string
+    :return: a DNSSEC algorithm value
+    :rtype: integer
     """
 
     value = _algorithm_by_text.get(text.upper())
@@ -107,7 +110,10 @@ def algorithm_from_text(text):
 def algorithm_to_text(value):
     """Convert a DNSSEC algorithm value to text
 
-    Returns a ``str``.
+    :param value: Value of a DNSSEC algorithm
+    :type value: integer
+    :return: the name of a DNSSEC algorithm
+    :rtype: string
     """
 
     text = _algorithm_by_value.get(value)
@@ -125,10 +131,13 @@ def _to_rdata(record, origin):
 def key_id(key, origin=None):
     """Return the key id (a 16-bit number) for the specified key.
 
-    Note the *origin* parameter of this function is historical and
-    is not needed.
+    :param key: a DNSKEY
+    :type key: :py:data:`dns.rdtypes.ANY.DNSKEY`
+    :param origin: Parameter is historical and **NOT** needed, defaults to None
+    :type origin: [type], optional
+    :return: an integer between 0 and 65535
+    :rtype: integer
 
-    Returns an ``int`` between 0 and 65535.
     """
 
     rdata = _to_rdata(key, origin)
@@ -148,19 +157,19 @@ def key_id(key, origin=None):
 def make_ds(name, key, algorithm, origin=None):
     """Create a DS record for a DNSSEC key.
 
-    *name* is the owner name of the DS record.
-
-    *key* is a ``dns.rdtypes.ANY.DNSKEY``.
-
-    *algorithm* is a string describing which hash algorithm to use.  The
-    currently supported hashes are "SHA1" and "SHA256".  Case does not
-    matter for these strings.
-
-    *origin* is a ``dns.name.Name`` and will be used as the origin
-    if *key* is a relative name.
-
-    Returns a ``dns.rdtypes.ANY.DS``.
+    :param name: Owner name of the DS record
+    :type name: string
+    :param key: a DNSKEY
+    :type key: :py:data:`dns.rdtypes.ANY.DNSKEY`
+    :param algorithm: a string describing which hash algorithm to use.The currently supported hashes are "SHA1" and "SHA256". Case does not matter for these strings.
+    :type algorithm: string
+    :param origin: Will be used as origin if `key` is a relative name, defaults to None
+    :type origin: :py:data:`dns.name.Name`, optional
+    :raises UnsupportedAlgorithm: If the algorithm is not either "SHA1" or "SHA256" exception will be thrown
+    :return: a DS record
+    :rtype: :py:data:`dns.rdtypes.ANY.DS`
     """
+
     if algorithm.upper() == 'SHA1':
         dsalg = 1
         dshash = hashlib.sha1()
@@ -272,22 +281,27 @@ def _make_algorithm_id(algorithm):
 def _validate_rrsig(rrset, rrsig, keys, origin=None, now=None):
     """Validate an RRset against a single signature rdata
 
-    The owner name of *rrsig* is assumed to be the same as the owner name
-    of *rrset*.
-
-    *rrset* is the RRset to validate.  It can be a ``dns.rrset.RRset`` or
-    a ``(dns.name.Name, dns.rdataset.Rdataset)`` tuple.
-
-    *rrsig* is a ``dns.rdata.Rdata``, the signature to validate.
-
-    *keys* is the key dictionary, used to find the DNSKEY associated with
-    a given name.  The dictionary is keyed by a ``dns.name.Name``, and has
-    ``dns.node.Node`` or ``dns.rdataset.Rdataset`` values.
-
-    *origin* is a ``dns.name.Name``, the origin to use for relative names.
-
-    *now* is an ``int``, the time to use when validating the signatures,
-    in seconds since the UNIX epoch.  The default is the current time.
+    :param rrset: The RRset to validate
+    :type rrset: :py:data:`dns.rrset.RRset` or (:py:data:`dns.name.Name`, :py:data:`dns.rdataset.Rdataset`)
+    :param rrsig: Signature to validate
+    :type rrsig: :py:data:`dns.rdata.Rdata`
+    :param keys: Key dictionary, used to find the DNSKEY associated with a given name.  The dictionary is keyed by a :py:data:`dns.name.Name`, and has :py:data:`dns.node.Node` or :py:data:`dns.rdataset.Rdataset` values.
+    :type keys: dictionary
+    :param origin: Origin to use for relative name, defaults to None
+    :type origin: :py:data:`dns.name.Name`, optional
+    :param now: time to use when validating the signatures, in seconds since the UNIX epoch, defaults to current time
+    :type now: integer, optional
+    :raises ValidationFailure: RRSig expired
+    :raises ValidationFailure: RRSig not yet valid
+    :raises ValidationFailure: Invalid public key
+    :raises ValidationFailure: Invalid ECDSA key
+    :raises ValidationFailure: Unknown algorithm
+    :raises ValueError: Generic Value Error
+    :raises ValidationFailure: Verify failure
+    :return: none
+    :rtype: none
+
+    .. todo:: Fill in missing infos
     """
 
     if isinstance(origin, str):
@@ -425,20 +439,18 @@ def _validate_rrsig(rrset, rrsig, keys, origin=None, now=None):
 def _validate(rrset, rrsigset, keys, origin=None, now=None):
     """Validate an RRset.
 
-    *rrset* is the RRset to validate.  It can be a ``dns.rrset.RRset`` or
-    a ``(dns.name.Name, dns.rdataset.Rdataset)`` tuple.
-
-    *rrsigset* is the signature RRset to be validated.  It can be a
-    ``dns.rrset.RRset`` or a ``(dns.name.Name, dns.rdataset.Rdataset)`` tuple.
-
-    *keys* is the key dictionary, used to find the DNSKEY associated with
-    a given name.  The dictionary is keyed by a ``dns.name.Name``, and has
-    ``dns.node.Node`` or ``dns.rdataset.Rdataset`` values.
-
-    *origin* is a ``dns.name.Name``, the origin to use for relative names.
-
-    *now* is an ``int``, the time to use when validating the signatures,
-    in seconds since the UNIX epoch.  The default is the current time.
+    :param rrset: RRset to validate
+    :type rrset: :py:data:`dns.rrset.RRset` or (:py:data:`dns.name.Name`, :py:data:`dns.rdataset.Rdataset`) tuple
+    :param rrsigset: Signature RRset to be validated
+    :type rrsigset: :py:data`dns.rrset.RRset` or (:py:data:`dns.name.Name`, :py:data:`dns.rdataset.Rdataset`) tuple
+    :param keys: Key dictionary, used to find the DNSKEY associated with a given name.  The dictionary is keyed by a :py:data:`dns.name.Name`, and has :py:data:`dns.node.Node` or :py:data:`dns.rdataset.Rdataset` values.
+    :type keys: dictionary
+    :param origin: Origin to use for relative name, defaults to None
+    :type origin: :py:data:`dns.name.Name`, optional
+    :param now: time to use when validating the signatures, in seconds since the UNIX epoch, defaults to current time
+    :type now: integer, optional
+    :raises ValidationFailure: Owner names do not match
+    :raises ValidationFailure: No RRSIGs validated
     """
 
     if isinstance(origin, str):

diff --git a/doc/conf.py b/doc/conf.py
index 10211f95774d457cafc7bbbe3de35c22b06d0c06..f6595afc73f81552262c1297ba7aadc4e31a53dd 100644 (file)
--- a/doc/conf.py
+++ b/doc/conf.py
@@ -31,9 +31,12 @@ sys.path.insert(0, os.path.abspath('..'))
 # 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',
+extensions = [
+    'sphinx.ext.autodoc',
     'sphinx.ext.viewcode',
-    'sphinx.ext.githubpages']
+    'sphinx.ext.githubpages',
+    'sphinx.ext.todo'
+    ]
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
@@ -77,7 +80,7 @@ exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
 pygments_style = 'sphinx'
 
 # If true, `todo` and `todoList` produce output, else they produce nothing.
-todo_include_todos = False
+todo_include_todos = True
 
 # -- Options for autodoc --------------------------------------------------
 
@@ -99,7 +102,7 @@ html_theme = 'alabaster'
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
-html_static_path = ['_static']
+# html_static_path = ['_static']
 
 # -- Options for HTMLHelp output ------------------------------------------
 
@@ -156,6 +159,3 @@ texinfo_documents = [
      author, 'dnspython', 'One line description of project.',
      'Miscellaneous'),
 ]
-
-
-

diff --git a/doc/dnssec.rst b/doc/dnssec.rst
index 115f9734ae941357203caf8e91a7759d92733df0..eee8ea741e8e618d96fc3362e40cfe02bd44b180 100644 (file)
--- a/doc/dnssec.rst
+++ b/doc/dnssec.rst
@@ -9,6 +9,14 @@ facilities for signing.  In order to use DNSSEC functions, you must have
 ``pycryptodome`` or ``pycryptodomex`` installed.  If you want to do elliptic
 curves, you must also have ``ecdsa`` installed.
 
+DNSSEC Functions
+----------------
+
+.. autofunction:: dns.dnssec.algorithm_from_text
+.. autofunction:: dns.dnssec.algorithm_to_text
+.. autofunction:: dns.dnssec.key_id
+.. autofunction:: dns.dnssec.make_ds
+
 DNSSEC Algorithms
 -----------------
 
@@ -25,14 +33,4 @@ DNSSEC Algorithms
 .. autodata:: dns.dnssec.ECDSAP384SHA384
 .. autodata:: dns.dnssec.INDIRECT
 .. autodata:: dns.dnssec.PRIVATEDNS
-.. autodata:: dns.dnssec.PRIVATEOID
-
-DNSSEC Functions
-----------------
-
-.. autofunction:: dns.dnssec.algorithm_from_text
-.. autofunction:: dns.dnssec.algorithm_to_text
-.. autofunction:: dns.dnssec.key_id
-.. autofunction:: dns.dnssec.make_ds
-.. autofunction:: dns.dnssec.validate
-.. autofunction:: dns.dnssec.validate_rrsig
+.. autodata:: dns.dnssec.PRIVATEOID
\ No newline at end of file