Merge remote-tracking branch 'macartur/issue-#211' into release-2017.1b3

Fix "more than one target found for cross-reference"
Fix #211

Conflicts:
	CHANGELOG.rst

Author: Diego Rabatone Oliveira

CHANGELOG.rst

@@ -37,6 +37,7 @@ Changed
 Fixed
 =====
 - [v0x01] Fixed method to unpack error messages.
+- documentation: fixed links and build warnings.
 - A few bug fixes.
 
 

docs/.gitignore

@@ -1,3 +1,2 @@
 _rebuild
-modules.rst
 python.inv

docs/Makefile

@@ -2,7 +2,7 @@
 #
 
 # You can set these variables from the command line.
-SPHINXOPTS    =
+SPHINXOPTS    = -W
 SPHINXBUILD   = sphinx-build
 PAPER         =
 BUILDDIR      = _build
@@ -61,7 +61,7 @@ clean:
 
 .PHONY: html
 html:
-	sphinx-apidoc -o . ../pyof/ -d10 -M
+	sphinx-apidoc -o . ../pyof/ -d10 -M -T
 	sed -i "/Submodules/,+1d" *.rst
 	sed -i "/Subpackages/,+1d" *.rst
 	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
@@ -70,7 +70,7 @@ html:
 
 .PHONY: dirhtml
 dirhtml:
-	sphinx-apidoc -o . ../pyof/ -d10 -M
+	sphinx-apidoc -o . ../pyof/ -d10 -M -T
 	sed -i "/Submodules/,+1d" *.rst
 	sed -i "/Subpackages/,+1d" *.rst
 	$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
@@ -242,7 +242,7 @@ dummy:
 	@echo "Build finished. Dummy builder generates no files."
 
 livehtml:
-	sphinx-apidoc -o . ../pyof/ -d10 -M
+	sphinx-apidoc -o . ../pyof/ -d10 -M -T
 	sed -i "/Submodules/,+1d" *.rst
 	sed -i "/Subpackages/,+1d" *.rst
 	sphinx-autobuild -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml -z ../pyof

docs/conf.py

@@ -111,6 +111,9 @@
 # If true, keep warnings as "system message" paragraphs in the built documents.
 #keep_warnings = False
 
+# Remove nonlocal_uri warnings
+suppress_warnings = ['image.nonlocal_uri']
+
 # If true, `todo` and `todoList` produce output, else they produce nothing.
 todo_include_todos = False
 
@@ -370,14 +373,8 @@
 # If true, do not generate a @detailmenu in the "Top" node's menu.
 #texinfo_no_detailmenu = False
 
-# Example configuration for intersphinx: refer to the Python standard library.
-# Note: links to Python doc only work if you are online or have python.inv
-#     file. To download it, run:
-#     curl https://docs.python.org/3/objects.inv >python.inv
-intersphinx_mapping = {'python': ('https://docs.python.org/3',
-                                  (None, 'python.inv')),
-                       'kytos': ('http://docs.kytos.io/kytos',
-                                 (None, 'kytos.inv'))}
+intersphinx_mapping = {'python': ('https://docs.python.org/3', None),
+                       'kytos': ('http://docs.kytos.io/kytos', None)}
 
 # Napoleon settings from http://www.sphinx-doc.org/en/stable/ext/napoleon.html
 napoleon_google_docstring = True

docs/get_involved.rst

@@ -5,5 +5,5 @@ We'd love for you to contribute to our source code and to make Kytos better
 than it is today!
 
 This is one component of the *Kytos* project. For more information on how to get
-involved, please, visit the section :doc:`kytos:get_involved` of the *Kytos*
+involved, please, visit the section :doc:`kytos:contributing` of the *Kytos*
 documentation.

docs/hacking.rst

@@ -2,7 +2,7 @@
 Hacking
 #######
 
-.. note:: Before reading this file, please read the :doc:`guidelines` section
+.. note:: Before reading this file, please read the :doc:`kytos:contributing` section
     that contains the main guidelines of the project.
 
 Development Environment Setup

docs/toc/introduction.rst

@@ -1,3 +1,5 @@
+:orphan:
+
 ############
 Introduction
 ############

pyof/foundation/base.py

@@ -5,9 +5,10 @@
 structs. You can realize that when you see a message class definition.
 
 A **struct** here is a group of basic attributes and/or struct attributes (i.e.
-:class:`~.common.header.Header`). A **message** here is like a struct, but all
-messages have a header attribute (i.e.
-:class:`~.asynchronous.packet_in.PacketIn`).
+:class:`~pyof.v0x01.common.header.Header`). A **message** here is like a
+struct, but all messages have a header attribute (i.e.
+:class:`~pyof.v0x01.asynchronous.packet_in.PacketIn`).
+
 
 The main classes of this module are :class:`GenericStruct`,
 :class:`GenericMessage`, :class:`GenericBitMask` and :class:`GenericType`.
@@ -50,7 +51,7 @@ def __init__(self, value=None, enum_ref=None):
 
         Args:
             value: The type's value.
-            enum_ref (:class:`type`): If :attr:`value` is from an Enum, specify
+            enum_ref (type): If :attr:`value` is from an Enum, specify
                 its type.
         """
         self._value = value
@@ -219,10 +220,10 @@ def is_valid(self):
             return False
 
     def isenum(self):
-        """Test whether it is an :class:`~Enum`.
+        """Test whether it is an :class:`~enum.Enum`.
 
         Returns:
-            bool: Whether it is an :class:`~Enum`.
+            bool: Whether it is an :class:`~enum.Enum`.
         """
         return self.enum_ref and issubclass(self.enum_ref, (Enum, IntEnum))
 
@@ -346,8 +347,8 @@ def get_pyof_version(module_fullname):
                 (e.g.: pyof.v0x01.common.header)
 
         Returns:
-            version (str): The module version, on the format 'v0x0?' if any. Or
-            None (None): If there isn't a version on the fullname.
+            str: The module version, on the format 'v0x0?' if any. Or None
+                  if there isn't a version on the fullname.
         """
         ver_module_re = re.compile(r'(pyof\.)(v0x\d+)(\..*)')
         matched = ver_module_re.match(module_fullname)
@@ -366,15 +367,16 @@ def replace_pyof_version(module_fullname, version):
 
         Args:
             module_fullname (str): The fullname of the module
-                (e.g.: pyof.v0x01.common.header)
+                                   (e.g.: pyof.v0x01.common.header)
             version (str): The version to be 'inserted' on the module fullname.
 
         Returns:
-            None (None): if the requested version is the same as the one of the
-                module_fullname or if the module_fullname is not a 'OF version'
-                specific module.
-            new_module_fullname (str): The new module fullname, with the
-                replaced version, on the format "pyof.v0x01.common.header".
+            str: module fullname
+                 The new module fullname, with the replaced version,
+                 on the format "pyof.v0x01.common.header". If the requested
+                 version is the same as the one of the module_fullname or if
+                 the module_fullname is not a 'OF version' specific module,
+                 returns None.
         """
         module_version = MetaStruct.get_pyof_version(module_fullname)
         if not module_version or module_version == version:
@@ -413,7 +415,7 @@ def get_pyof_obj_new_version(name, obj, new_version):
                 'obj'.
 
         Return:
-            (name, obj): A tuple in which the first item is the name of the
+            (str, obj): A tuple in which the first item is the name of the
                 class attribute (the same that was passed), and the second item
                 is a instance of the passed class attribute. If the class
                 attribute is not a pyof versioned attribute, then the same
@@ -655,8 +657,9 @@ def is_valid(self):
 
         This method will check whether all struct attributes have a proper
         value according to the OpenFlow specification. For instance, if you
-        have a struct with an attribute of type :class:`UBInt8()`
-        and you assign a string value to it, this method will return False.
+        have a struct with an attribute of type
+        :class:`~pyof.foundation.basic_types.UBInt8` and you assign a string
+        value to it, this method will return False.
 
         Returns:
             bool: Whether the struct is valid.

pyof/foundation/basic_types.py

@@ -401,9 +401,11 @@ def is_broadcast(self):
 class BinaryData(GenericType):
     """Class to create objects that represent binary data.
 
-    This is used in the ``data`` attribute from :class:`.PacketIn` and
-    :class:`.PacketOut` messages. Both the :meth:`pack` and :meth:`unpack`
-    methods will return the binary data itself. :meth:`get_size` method will
+    This is used in the ``data`` attribute from
+    :class:`~pyof.v0x01.asynchronous.packet_in.PacketIn` and
+    :class:`~pyof.v0x01.controller2switch.packet_out.PacketOut` messages.
+    Both the :meth:`pack` and :meth:`unpack` methods will return the
+    binary data itself. :meth:`get_size` method will
     return the size of the instance using Python's :func:`len`.
     """
 

pyof/v0x01/asynchronous/error_msg.py

@@ -170,7 +170,7 @@ class ErrorMsg(GenericMessage):
     This message does not contain a body in addition to the OpenFlow Header.
     """
 
-    #: :class:`~.header.Header`: OpenFlow Header
+    #: :class:`~pyof.v0x01.common.header.Header`: OpenFlow Header
     header = Header(message_type=Type.OFPT_ERROR)
     error_type = UBInt16(enum_ref=ErrorType)
     code = UBInt16()
@@ -181,10 +181,9 @@ def __init__(self, xid=None, error_type=None, code=None, data=b''):
 
         Args:
             xid (int): To be included in the message header.
-            error_type (ErrorType): Error type.
-            code (Enum): Error code.
-            data (:func:`bytes` or packable): Its content is based on the error
-                type and code.
+            error_type (:class:`ErrorType`): Error type.
+            code (enum.IntEnum): Error code.
+            data (bytes): Its content is based on the error type and code.
         """
         super().__init__(xid)
         self.error_type = error_type
@@ -217,7 +216,18 @@ def pack(self, value=None):
             raise PackException(msg)
 
     def unpack(self, buff, offset=0):
-        """Unpack binary data into python object."""
+        """Unpack *buff* into this object.
+
+        This method will convert a binary data into a readable value according
+        to the attribute format.
+
+        Args:
+            buff (bytes): Binary buffer.
+            offset (int): Where to begin unpacking.
+
+        Raises:
+            :exc:`~.exceptions.UnpackException`: If unpack fails.
+        """
         super().unpack(buff, offset)
         CodeClass = ErrorType(self.error_type).get_class()
         self.code = CodeClass(self.code)