diff --git a/README.md b/README.md
index 1ab115e0c514441c5eea96d097297547cd5b84b9..930f804a0d192b076697f06e549692c18de4d8a6 100644
--- a/README.md
+++ b/README.md
@@ -19,9 +19,9 @@ cache poisoning, VOIP decoding on WEP encrypted channel, ...),
etc.
See
-[interactive tutorial](http://www.secdev.org/projects/scapy/doc/usage.html#interactive-tutorial)
+[interactive tutorial](http://scapy.readthedocs.io/en/latest/usage.html#interactive-tutorial)
and
-[the quick demo: an interactive session](http://www.secdev.org/projects/scapy/demo.html)
+[the quick demo: an interactive session](http://scapy.readthedocs.io/en/latest/introduction.html#quick-demo)
(some examples may be outdated).
# Contributing #
diff --git a/doc/scapy/build_dissect.rst b/doc/scapy/build_dissect.rst
index 9add39bab2eb609077af101e2041324120974c76..6f9926d867be48b8f14affab9c60675ee3441c88 100644
--- a/doc/scapy/build_dissect.rst
+++ b/doc/scapy/build_dissect.rst
@@ -1104,3 +1104,15 @@ Other protocols
TimeStampField # NTP (BitField)
+Design patterns
+===============
+Some patterns are similar to a lot of protocols and thus can be described the same way in Scapy.
+
+The following parts will present several models and conventions that can be followed when implementing a new protocol.
+
+Field naming convention
+-----------------------
+The goal is to keep the writing of packets fluent and intuitive. The basic instructions are the following :
+
+* Use inverted camel case and common abbreviations (e.g. len, src, dst, dstPort, srcIp).
+* Wherever it is either possible or relevant, prefer using the names from the specifications. This aims to help newcomers to easily forge packets.
diff --git a/doc/scapy/development.rst b/doc/scapy/development.rst
index a29bd8b05eab2f37605cbce0175b6b79213f75e3..63118b8563e28e93099ac11ff4aa157177779472 100644
--- a/doc/scapy/development.rst
+++ b/doc/scapy/development.rst
@@ -26,6 +26,54 @@ How to contribute
<https://github.com/secdev/scapy/wiki/Contrib:-PacketSamples>`_.
+Improve the documentation
+=========================
+
+The documentation can be improved in several ways by:
+
+* Adding docstrings to the source code.
+* Adding usage examples to the documentation.
+
+Adding Docstrings
+-----------------
+The Scapy source code have few explanations of what a function is doing. A docstring, by adding explanation and
+expected input and output parameters, helps saving time for both the layer developers and the users looking for
+advanced features.
+
+An example of docstring from the ``scapy.fields.FlagsField`` class: ::
+
+ class FlagsField(BitField):
+ """ Handle Flag type field
+
+ Make sure all your flags have a label
+
+ Example:
+ >>> from scapy.packet import Packet
+ >>> class FlagsTest(Packet):
+ fields_desc = [FlagsField("flags", 0, 8, ["f0", "f1", "f2", "f3", "f4", "f5", "f6", "f7"])]
+ >>> FlagsTest(flags=9).show2()
+ ###[ FlagsTest ]###
+ flags = f0+f3
+ >>> FlagsTest(flags=0).show2().strip()
+ ###[ FlagsTest ]###
+ flags =
+
+ :param name: field's name
+ :param default: default value for the field
+ :param size: number of bits in the field
+ :param names: (list or dict) label for each flag, Least Significant Bit tag's name is written first
+ """
+
+It will contain a short oneline description of the class followed by some indications about its usage.
+You can add a usage example if it makes sense using the `doctest <https://docs.python.org/2.7/library/doctest.html>`_ format.
+Finally the classic python signature can be added following the `sphinx documentation <http://www.sphinx-doc.org/en/stable/domains.html#python-signatures>`_.
+
+This task works in pair with writing non regression unit tests.
+
+Documentation
+-------------
+A way to improve the documentation content is by keeping it up to date with the latest version of Scapy. You can also help by adding usage examples of your own or directly gathered from existing online Scapy presentations.
+
Testing with UTScapy
====================
diff --git a/doc/scapy/installation.rst b/doc/scapy/installation.rst
index 5086a7fd253f9cc9da7ca35fc5553da015da4ec8..c59a374f6e55b64da0b9f5d194413192c808bac2 100644
--- a/doc/scapy/installation.rst
+++ b/doc/scapy/installation.rst
@@ -416,6 +416,52 @@ Known bugs
* Packets cannot be sent to localhost (or local IP addresses on your own host).
* The ``voip_play()`` functions do not work because they output the sound via ``/dev/dsp`` which is not available on Windows.
-
+Build the documentation offline
+===============================
+The Scapy project's documentation is written using reStructuredText (files \*.rst) and can be built using
+the `Sphinx <http://www.sphinx-doc.org/>`_ python library. The official online version is available
+on `readthedocs <http://scapy.readthedocs.io/>`_.
+
+HTML version
+------------
+The instructions to build the HTML version are: ::
+
+ (activate a virtualenv)
+ pip install sphinx
+ cd doc/scapy
+ make html
+
+You can now open the resulting HTML file ``_build/html/index.html`` in your favorite web browser.
+
+To use the ReadTheDocs' template, you will have to install the corresponding theme with: ::
+
+ pip install sphinx_rtd_theme
+
+and edit the doc/scapy/conf.py file to have: ::
+
+ import sphinx_rtd_theme
+ #html_style = 'default.css'
+ html_theme = "sphinx_rtd_theme"
+ html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
+
+Note: make sure you commented out the ``html_style`` variable.
+
+UML diagram
+-----------
+Using ``pyreverse`` you can build an UML representation of the Scapy source code's object hierarchy. Here is an
+example on how to build the inheritence graph for the Fields objects : ::
+
+ (activate a virtualenv)
+ pip install pylint
+ cd scapy/
+ pyreverse -o png -p fields scapy/fields.py
+
+This will generate a ``classes_fields.png`` picture containing the inheritance hierarchy. Note that you can provide as many
+modules or packages as you want, but the result will quickly get unreadable.
+
+To see the dependencies between the DHCP layer and the ansmachine module, you can run: ::
+
+ pyreverse -o png -p dhcp_ans scapy/ansmachine.py scapy/layers/dhcp.py scapy/packet.py
+In this case, Pyreverse will also generate a ``packages_dhcp_ans.png`` showing the link between the different python modules provided.
diff --git a/scapy/fields.py b/scapy/fields.py
index d978e6e66f67d3a117bda23e5a6fa1b4150cd53a..82ada5ef9167b3b97c1bf5cc36290d64f3600a6c 100644
--- a/scapy/fields.py
+++ b/scapy/fields.py
@@ -933,6 +933,26 @@ class LEFieldLenField(FieldLenField):
class FlagsField(BitField):
+ """ Handle Flag type field
+
+ Make sure all your flags have a label
+
+ Example:
+ >>> from scapy.packet import Packet
+ >>> class FlagsTest(Packet):
+ fields_desc = [FlagsField("flags", 0, 8, ["f0", "f1", "f2", "f3", "f4", "f5", "f6", "f7"])]
+ >>> FlagsTest(flags=9).show2()
+ ###[ FlagsTest ]###
+ flags = f0+f3
+ >>> FlagsTest(flags=0).show2().strip()
+ ###[ FlagsTest ]###
+ flags =
+
+ :param name: field's name
+ :param default: default value for the field
+ :param size: number of bits in the field
+ :param names: (list or dict) label for each flag, Least Significant Bit tag's name is written first
+ """
__slots__ = ["multi", "names"]
def __init__(self, name, default, size, names):
self.multi = type(names) is list