Skip to content

Scapy docs massive cleanup #1865

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 6 commits into from
Mar 30, 2019
Merged

Scapy docs massive cleanup #1865

merged 6 commits into from
Mar 30, 2019

Conversation

gpotter2
Copy link
Member

@gpotter2 gpotter2 commented Feb 22, 2019

Massive doc overhaul:

  • split the bottom of Advanced usage into separate layer-specific files
  • Refactor the documentation sidebar (aka :toctree:)
  • remove references to the deprecated Scapy 1.X
  • fix permissions on polybassa 's .svg files + replace old Usage screenshot by fancy SVG animation in Introduction
  • adds scapy versions / python version graph
  • fixes windows logs when winpcap/npcap ins't installed + color of logs
  • small fixes in doc
  • remove the tiny "Python tutorial" from => it's not useful, and is incomplete. We're illegitimate to give this lesson (in Introduction)
  • Document #scapy.contrib.*

SVGs animation are light, well-supported (except on Microsoft Edge, but it isn't used much, and will be soon switching to a Chromium implementation which supports it), and make the doc much more readable. It was first used in the Automative doc, and it's a great idea. I think we could try to implement them more often.

Screenshots

image

@gpotter2 gpotter2 added doc cleanup Performs some code clean-up labels Feb 22, 2019
@codecov
Copy link

codecov bot commented Feb 22, 2019

Codecov Report

Merging #1865 into master will increase coverage by 3.13%.
The diff coverage is 12.5%.

@@            Coverage Diff             @@
##           master    #1865      +/-   ##
==========================================
+ Coverage   80.56%   83.69%   +3.13%     
==========================================
  Files         180      185       +5     
  Lines       40906    42479    +1573     
==========================================
+ Hits        32954    35553    +2599     
+ Misses       7952     6926    -1026
Impacted Files Coverage Δ
scapy/arch/windows/__init__.py 71.76% <0%> (ø)
scapy/arch/pcapdnet.py 46.42% <0%> (ø)
scapy/themes.py 86.71% <20%> (-0.98%) ⬇️
scapy/arch/windows/structures.py 88.42% <0%> (ø)
scapy/arch/windows/native.py 78.84% <0%> (ø)
scapy/arch/bpf/supersocket.py 27.6% <0%> (ø)
scapy/fields.py 91.63% <0%> (+0.14%) ⬆️
scapy/layers/dns.py 91.52% <0%> (+0.2%) ⬆️
... and 49 more

@codecov
Copy link

codecov bot commented Feb 22, 2019

Codecov Report

Merging #1865 into master will increase coverage by 0.01%.
The diff coverage is 12.5%.

@@            Coverage Diff             @@
##           master    #1865      +/-   ##
==========================================
+ Coverage   85.85%   85.86%   +0.01%     
==========================================
  Files         187      187              
  Lines       42773    42781       +8     
==========================================
+ Hits        36723    36736      +13     
+ Misses       6050     6045       -5
Impacted Files Coverage Δ
scapy/arch/pcapdnet.py 57.03% <0%> (ø) ⬆️
scapy/arch/windows/__init__.py 71.76% <0%> (-0.23%) ⬇️
scapy/themes.py 79.15% <20%> (-0.78%) ⬇️
scapy/sendrecv.py 85.25% <0%> (-0.17%) ⬇️
scapy/layers/l2.py 84.36% <0%> (ø) ⬆️
scapy/packet.py 79.07% <0%> (+0.03%) ⬆️
scapy/layers/ntp.py 92.04% <0%> (+0.53%) ⬆️
scapy/config.py 86.6% <0%> (+0.89%) ⬆️
scapy/autorun.py 82.64% <0%> (+4.13%) ⬆️

This was referenced Feb 22, 2019
@gpotter2
Copy link
Member Author

gpotter2 commented Feb 24, 2019

This is ready to be merged.
The PR is simple enough, mostly doc fixes.

I first tried to make those really cool Gantt-alike graphs, that Ubuntu has for instance, but ended up with a more simple table

@gpotter2
Copy link
Member Author

gpotter2 commented Mar 23, 2019

@guedou @p-l- Sorry for the ping, I'd really like to have this merged.

@gpotter2 gpotter2 changed the title Improve doc & fix windows logs Scapy docs massive cleanup Mar 24, 2019
@gpotter2
Copy link
Member Author

I’ve rebased to fix the conflicts

@guedou
Copy link
Member

guedou commented Mar 24, 2019

As far as I remember, v2.3.3 was the latest version to support Python 2.5.

@gpotter2
Copy link
Member Author

gpotter2 commented Mar 24, 2019

You are right
AADED430-74BD-41DE-BF9F-990F3530F42B
70356252-AD02-41CB-A1D3-97941B47B71E
I’ve included the .obs used to make the chart, and regenerate the image. I’ll update it when I get the time.

Note: the image name should not be changed, as Scapy.net download page is linking it via its raw.github.com link

@polybassa
Copy link
Contributor

@epozzobon made a script to convert svg files from termtosvg to webm videos. If this is helpful, we can share these scripts for the documentation. On advantage of videos is play, pause and scrolling.

@polybassa
Copy link
Contributor

Many hands on examples are similar to unit tests. Do you think, it would be possible to generate hands on examples from uts files? This would have the advantage, that even the code snippets in the documentation are checked from the CI environment. It's very annoying if code snippets in the documentation are outdated.

I could imagine something like a special tag on a unit test step. This will indicate a new script to export this test as example snippet. The test name could than be used as headline. Explanation can be between the code as comments.

@guedou
Copy link
Member

guedou commented Mar 25, 2019

@polybassa I like our idea of using the unit tests for the documentation!

@polybassa
Copy link
Contributor

The easiest way would probably be a script, which checks for a specific tag and then copies the related unit test as .rst file into a specific folder. The documentation can then include this file as example snippet.

@guedou
Copy link
Member

guedou commented Mar 29, 2019

Can I merge this?

@gpotter2
Copy link
Member Author

Should be mergeable !

@guedou guedou merged commit 54b8d50 into secdev:master Mar 30, 2019
@gpotter2 gpotter2 deleted the winwarns branch April 29, 2019 13:26
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
cleanup Performs some code clean-up doc
Projects
None yet
Development

Successfully merging this pull request may close these issues.

3 participants