doc improvement proposal (#207)

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 #

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.

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

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.

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