Scapy docs massive cleanup

CONTRIBUTING.md

@@ -97,6 +97,8 @@ To be precise, `scapy/layers` protocols should not be importing `scapy/contrib`
 protocols, whereas `scapy/contrib` protocols may import both `scapy/contrib` and
 `scapy/layers` protocols.
 
+The detailed requirements are explained in [Design patterns](https://scapy.readthedocs.io/en/latest/build_dissect.html#design-patterns) on Scapy's doc.
+
 ### Features
 
 Protocol-related features should be implemented within the same module

doc/scapy/build_dissect.rst

@@ -1128,3 +1128,24 @@ The goal is to keep the writing of packets fluent and intuitive. The basic instr
 
 * 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.
+
+Add new protocols to Scapy
+--------------------------
+
+New protocols can go either in ``scapy/layers`` or to ``scapy/contrib``. Protocols in ``scapy/layers`` should be usually found on common networks, while protocols in ``scapy/contrib`` should be uncommon or specific.
+
+To be precise, ``scapy/layers`` protocols should not be importing ``scapy/contrib`` protocols, whereas ``scapy/contrib`` protocols may import both ``scapy/contrib`` and ``scapy/layers`` protocols.
+
+Scapy provides an ``explore()`` function, to search through the available layer/contrib modules. Therefore, modules contributed back to Scapy must provide information about them, knowingly:
+
+- A **contrib** module must have defined, near the top of the module (below the license header is a good place) **(without the brackets)** `Example <https://github.com/secdev/scapy/blob/0f6ac82ed66919a20226a3d8d164b810c8eb293c/scapy/contrib/openflow.py#L11-L12>`_ ::
+
+    # scapy.contrib.description = [...]
+    # scapy.contrib.status = [...]
+    # scapy.contrib.name = [...] (optional)
+
+- If the contrib module does not contain any packets, and should not be indexed in `explore()`, then you should instead set::
+
+    # scapy.contrib.status = skip 
+
+- A **layer** module must have a docstring, in which the first line shortly describes the module.

doc/scapy/index.rst

@@ -17,17 +17,32 @@ This document is under a `Creative Commons Attribution - Non-Commercial
 
 .. toctree::
    :maxdepth: 2
+   :caption: General documentation
 
    introduction
    installation
 
    usage
    advanced_usage
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Extend scapy
+
    extending
    build_dissect
    functions
 
-   bluetooth
+.. toctree::
+   :maxdepth: 2
+   :caption: Layer-specific documentation
+   :glob:
+
+   layers/index.rst
+
+.. toctree::
+   :maxdepth: 2
+   :caption: About
 
    troubleshooting
    development

doc/scapy/installation.rst

@@ -13,14 +13,12 @@ Overview
  3. (Optional): `Install additional software for special features <#optional-software-for-special-features>`_.
  4. Run Scapy with root privileges.
 
-Each of these steps can be done in a different way depending on your platform and on the version of Scapy you want to use. 
+Each of these steps can be done in a different way depending on your platform and on the version of Scapy you want to use.  Follow the platform-specific instructions for more detail.
 
-At the moment, there are two different versions of Scapy:
+Scapy versions
+==============
 
-* **Scapy v2.x**. The current up-to-date version. It consists of several files  packaged in the standard distutils way.
-  Scapy v2 <= 2.3.3 needs Python 2.5, Scapy v2 > 2.3.3 needs Python 2.7 or 3.4+.
-* **Scapy v1.x (deprecated)**. It does not support Python 3. It consists of only one file and works on Python 2.4, so it might be easier to install.
-  Moreover, your OS may already have specially prepared packages or ports for it. The last version is v1.2.2.
+.. image:: graphics/scapy_version_timeline.jpg
 
 .. note::
 
@@ -94,15 +92,6 @@ Then you can always update to the latest version::
 
    You can run scapy without installing it using the ``run_scapy`` (unix) or ``run_scapy.bat`` (Windows) script or running it directly from the executable zip file (see the previous section).
 
-Installing Scapy v1.2 (Deprecated)
-==================================
-
-As Scapy v1 consists only of one single Python file, installation is easy:
-Just download the last version and run it with your Python interpreter::
-
- $ wget https://github.com/raw/secdev/scapy/v1.2.0.2/scapy.py
- $ sudo python scapy.py
-
 Optional software for special features
 ======================================
 
@@ -339,9 +328,6 @@ Windows
 
 Scapy is primarily being developed for Unix-like systems and works best on those platforms. But the latest version of Scapy supports Windows out-of-the-box. So you can use nearly all of Scapy's features on your Windows machine as well.
 
-.. note::
-   If you update from Scapy-win v1.2.0.2 to Scapy v2 remember to use ``from scapy.all import *`` instead of ``from scapy import *``.
-
 .. image:: graphics/scapy-win-screenshot1.png
    :scale: 80
    :align: center

doc/scapy/introduction.rst

@@ -115,6 +115,9 @@ information is lost in this operation.
 Quick demo
 ==========
 
+.. image:: graphics/animations/animation-scapy-demo.svg
+   :align: center
+
 First, we play a bit and create four IP packets at once. Let's see how it works. We first instantiate the IP class. Then, we instantiate it again and we provide a destination that is worth four IP addresses (/30 gives the netmask). Using a Python idiom, we develop this implicit packet in a set of explicit packets. Then, we quit the interpreter. As we provided a session file, the variables we were working on are saved, then reloaded:: 
 
     # ./run_scapy -s mysession
@@ -187,25 +190,5 @@ Learning Python
 Scapy uses the Python interpreter as a command board. That means that you can directly use the Python language (assign variables, use loops, define functions, etc.)
 
 If you are new to Python and you really don't understand a word because of that, or if you want to learn this language, take an hour to read the very good `Python tutorial <http://docs.python.org/tutorial/>`_  by Guido Van Rossum. After that, you'll know Python :) (really!). For a more in-depth tutorial `Dive Into Python <http://diveintopython.org/>`_ is a very good start too.
-
-For a quick start, here's an overview of Python's data types:
-
-* ``int`` (signed, 32bits) : ``42`` 
-* ``long`` (signed, infinite): ``42L`` 
-* ``str`` : ``"bell\x07\n"`` or ``’bell\x07\n’`` 
-
-* ``tuple`` (immutable): ``(1,4,"42")`` 
-* ``list`` (mutable): ``[4,2,"1"]`` 
-* ``dict`` (mutable): ``{ "one":1 , "two":2 }``
-
-There are no block delimiters in Python. Instead, indentation does matter::
-
-    if cond:
-        instr
-        instr
-    elif cond2:
-        instr
-    else:
-        instr