From 443007a9768459e4a7e395ceaca891186ffd9695 Mon Sep 17 00:00:00 2001 From: Brian Wylie Date: Mon, 18 May 2015 17:17:57 -0600 Subject: [PATCH 1/6] adding initial docs framing for readthedocs --- .travis.yml | 1 + MANIFEST.in | 5 ++ docs/Makefile | 153 ++++++++++++++++++++++++++++++++++++++++++ docs/api/ethernet.rst | 9 +++ docs/api/http.rst | 15 +++++ docs/api/index.rst | 12 ++++ docs/api/ip.rst | 9 +++ docs/api/tcp.rst | 9 +++ docs/api/udp.rst | 9 +++ docs/authors.rst | 7 ++ docs/badges.rst | 41 +++++++++++ docs/changelog.rst | 4 ++ docs/conf.py | 74 ++++++++++++++++++++ docs/contributing.rst | 15 +++++ docs/examples.rst | 17 +++++ docs/index.rst | 44 ++++++++++++ docs/installation.rst | 8 +++ docs/license.rst | 2 + docs/plans.rst | 13 ++++ docs/quickstart.rst | 20 ++++++ docs/requirements.txt | 2 + tox.ini | 11 ++- 22 files changed, 473 insertions(+), 7 deletions(-) create mode 100644 docs/Makefile create mode 100644 docs/api/ethernet.rst create mode 100644 docs/api/http.rst create mode 100644 docs/api/index.rst create mode 100644 docs/api/ip.rst create mode 100644 docs/api/tcp.rst create mode 100644 docs/api/udp.rst create mode 100644 docs/authors.rst create mode 100644 docs/badges.rst create mode 100644 docs/changelog.rst create mode 100644 docs/conf.py create mode 100644 docs/contributing.rst create mode 100644 docs/examples.rst create mode 100644 docs/index.rst create mode 100644 docs/installation.rst create mode 100644 docs/license.rst create mode 100644 docs/plans.rst create mode 100644 docs/quickstart.rst create mode 100644 docs/requirements.txt diff --git a/.travis.yml b/.travis.yml index ab02e22..b32235b 100644 --- a/.travis.yml +++ b/.travis.yml @@ -7,6 +7,7 @@ env: - TOXENV=py26,coveralls - TOXENV=py27,coveralls - TOXENV=pypy,coveralls + - TOXENV=docs before_install: - python --version - virtualenv --version diff --git a/MANIFEST.in b/MANIFEST.in index e96d54c..2d5c155 100644 --- a/MANIFEST.in +++ b/MANIFEST.in @@ -1,2 +1,7 @@ include AUTHORS CHANGES README.rst LICENSE + +recursive-include docs * +prune docs/_build + +global-exclude __pycache__/* diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 0000000..2687c75 --- /dev/null +++ b/docs/Makefile @@ -0,0 +1,153 @@ +# Makefile for Sphinx documentation +# + +# You can set these variables from the command line. +SPHINXOPTS = +SPHINXBUILD = sphinx-build +PAPER = +BUILDDIR = _build + +# Internal variables. +PAPEROPT_a4 = -D latex_paper_size=a4 +PAPEROPT_letter = -D latex_paper_size=letter +ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . +# the i18n builder cannot share the environment and doctrees with the others +I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . + +.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext + +help: + @echo "Please use \`make ' where is one of" + @echo " html to make standalone HTML files" + @echo " dirhtml to make HTML files named index.html in directories" + @echo " singlehtml to make a single large HTML file" + @echo " pickle to make pickle files" + @echo " json to make JSON files" + @echo " htmlhelp to make HTML files and a HTML help project" + @echo " qthelp to make HTML files and a qthelp project" + @echo " devhelp to make HTML files and a Devhelp project" + @echo " epub to make an epub" + @echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter" + @echo " latexpdf to make LaTeX files and run them through pdflatex" + @echo " text to make text files" + @echo " man to make manual pages" + @echo " texinfo to make Texinfo files" + @echo " info to make Texinfo files and run them through makeinfo" + @echo " gettext to make PO message catalogs" + @echo " changes to make an overview of all changed/added/deprecated items" + @echo " linkcheck to check all external links for integrity" + @echo " doctest to run all doctests embedded in the documentation (if enabled)" + +clean: + -rm -rf $(BUILDDIR)/* + +html: + $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html + @echo + @echo "Build finished. The HTML pages are in $(BUILDDIR)/html." + +dirhtml: + $(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml + @echo + @echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml." + +singlehtml: + $(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml + @echo + @echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml." + +pickle: + $(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle + @echo + @echo "Build finished; now you can process the pickle files." + +json: + $(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json + @echo + @echo "Build finished; now you can process the JSON files." + +htmlhelp: + $(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp + @echo + @echo "Build finished; now you can run HTML Help Workshop with the" \ + ".hhp project file in $(BUILDDIR)/htmlhelp." + +qthelp: + $(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp + @echo + @echo "Build finished; now you can run "qcollectiongenerator" with the" \ + ".qhcp project file in $(BUILDDIR)/qthelp, like this:" + @echo "# qcollectiongenerator $(BUILDDIR)/qthelp/pyspotify.qhcp" + @echo "To view the help file:" + @echo "# assistant -collectionFile $(BUILDDIR)/qthelp/pyspotify.qhc" + +devhelp: + $(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp + @echo + @echo "Build finished." + @echo "To view the help file:" + @echo "# mkdir -p $$HOME/.local/share/devhelp/pyspotify" + @echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/pyspotify" + @echo "# devhelp" + +epub: + $(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub + @echo + @echo "Build finished. The epub file is in $(BUILDDIR)/epub." + +latex: + $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex + @echo + @echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex." + @echo "Run \`make' in that directory to run these through (pdf)latex" \ + "(use \`make latexpdf' here to do that automatically)." + +latexpdf: + $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex + @echo "Running LaTeX files through pdflatex..." + $(MAKE) -C $(BUILDDIR)/latex all-pdf + @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex." + +text: + $(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text + @echo + @echo "Build finished. The text files are in $(BUILDDIR)/text." + +man: + $(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man + @echo + @echo "Build finished. The manual pages are in $(BUILDDIR)/man." + +texinfo: + $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo + @echo + @echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo." + @echo "Run \`make' in that directory to run these through makeinfo" \ + "(use \`make info' here to do that automatically)." + +info: + $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo + @echo "Running Texinfo files through makeinfo..." + make -C $(BUILDDIR)/texinfo info + @echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo." + +gettext: + $(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale + @echo + @echo "Build finished. The message catalogs are in $(BUILDDIR)/locale." + +changes: + $(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes + @echo + @echo "The overview file is in $(BUILDDIR)/changes." + +linkcheck: + $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck + @echo + @echo "Link check complete; look for any errors in the above output " \ + "or in $(BUILDDIR)/linkcheck/output.txt." + +doctest: + $(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest + @echo "Testing of doctests in the sources finished, look at the " \ + "results in $(BUILDDIR)/doctest/output.txt." diff --git a/docs/api/ethernet.rst b/docs/api/ethernet.rst new file mode 100644 index 0000000..fb2c05f --- /dev/null +++ b/docs/api/ethernet.rst @@ -0,0 +1,9 @@ +******** +Ethernet +******** + +.. module:: dpkt.ethernet + +.. autoclass:: Ethernet + :members: + diff --git a/docs/api/http.rst b/docs/api/http.rst new file mode 100644 index 0000000..f03b842 --- /dev/null +++ b/docs/api/http.rst @@ -0,0 +1,15 @@ +**** +HTTP +**** + +.. module:: dpkt.http + +.. autoclass:: Message + :members: + +.. autoclass:: Request + :members: + +.. autoclass:: Response + :members: + diff --git a/docs/api/index.rst b/docs/api/index.rst new file mode 100644 index 0000000..257e683 --- /dev/null +++ b/docs/api/index.rst @@ -0,0 +1,12 @@ +The dpkt API reference + +**Sections** + +.. toctree:: + :maxdepth: 1 + + ethernet + ip + udp + tcp + http diff --git a/docs/api/ip.rst b/docs/api/ip.rst new file mode 100644 index 0000000..f40a30b --- /dev/null +++ b/docs/api/ip.rst @@ -0,0 +1,9 @@ +** +IP +** + +.. module:: dpkt.ip + +.. autoclass:: IP + :members: + diff --git a/docs/api/tcp.rst b/docs/api/tcp.rst new file mode 100644 index 0000000..500b33f --- /dev/null +++ b/docs/api/tcp.rst @@ -0,0 +1,9 @@ +*** +TCP +*** + +.. module:: dpkt.tcp + +.. autoclass:: TCP + :members: + diff --git a/docs/api/udp.rst b/docs/api/udp.rst new file mode 100644 index 0000000..8f30364 --- /dev/null +++ b/docs/api/udp.rst @@ -0,0 +1,9 @@ +*** +UDP +*** + +.. module:: dpkt.udp + +.. autoclass:: UDP + :members: + diff --git a/docs/authors.rst b/docs/authors.rst new file mode 100644 index 0000000..238aa6b --- /dev/null +++ b/docs/authors.rst @@ -0,0 +1,7 @@ +******* +Authors +******* + +.. include:: ../AUTHORS + +If you want to contribute to dpkt, see :doc:`contributing`. diff --git a/docs/badges.rst b/docs/badges.rst new file mode 100644 index 0000000..0c71fdd --- /dev/null +++ b/docs/badges.rst @@ -0,0 +1,41 @@ + + +| |docs| |travis| |coveralls| |landscape| |version| +| |downloads| |wheel| |supported-versions| |supported-implementations| + +.. |docs| image:: https://readthedocs.org/projects/dpkt/badge/?style=flat + :target: https://readthedocs.org/projects/dpkt + :alt: Documentation Status + +.. |travis| image:: http://img.shields.io/travis/kbandla/dpkt/master.png?style=flat + :alt: Travis-CI Build Status + :target: https://travis-ci.org/kbandla/dpkt + +.. |coveralls| image:: http://img.shields.io/coveralls/kbandla/dpkt/master.png?style=flat + :alt: Coverage Status + :target: https://coveralls.io/r/kbandla/dpkt + +.. |landscape| image:: https://landscape.io/github/kbandla/dpkt/master/landscape.svg?style=flat + :target: https://landscape.io/github/kbandla/dpkt/master + :alt: Code Quality Status + +.. |version| image:: http://img.shields.io/pypi/v/dpkt.png?style=flat + :alt: PyPI Package latest release + :target: https://pypi.python.org/pypi/dpkt + +.. |downloads| image:: http://img.shields.io/pypi/dm/dpkt.png?style=flat + :alt: PyPI Package monthly downloads + :target: https://pypi.python.org/pypi/dpkt + +.. |wheel| image:: https://pypip.in/wheel/dpkt/badge.png?style=flat + :alt: PyPI Wheel + :target: https://pypi.python.org/pypi/dpkt + +.. |supported-versions| image:: https://pypip.in/py_versions/dpkt/badge.png?style=flat + :alt: Supported versions + :target: https://pypi.python.org/pypi/dpkt + +.. |supported-implementations| image:: https://pypip.in/implementation/dpkt/badge.png?style=flat + :alt: Supported implementations + :target: https://pypi.python.org/pypi/dpkt + diff --git a/docs/changelog.rst b/docs/changelog.rst new file mode 100644 index 0000000..ac7e237 --- /dev/null +++ b/docs/changelog.rst @@ -0,0 +1,4 @@ +********* +Changelog +********* + diff --git a/docs/conf.py b/docs/conf.py new file mode 100644 index 0000000..06a8944 --- /dev/null +++ b/docs/conf.py @@ -0,0 +1,74 @@ +# encoding: utf-8 + +"""dpkt documentation build configuration file""" + +from __future__ import unicode_literals + +import os +import re +import sys +import types +import mock + + +def get_version(filename): + init_py = open(filename).read() + metadata = dict(re.findall("__([a-z]+)__ = '([^']+)'", init_py)) + return metadata['version'] + + +# -- Workarounds to have autodoc generate API docs ---------------------------- + +sys.path.insert(0, os.path.abspath('..')) + + +# Mock any objects that we might need to +foo = mock.Mock() +foo.__version__ = '0.1.1' +sys.modules['foo'] = foo + + +# -- General configuration ---------------------------------------------------- +needs_sphinx = '1.0' +extensions = [ + 'sphinx.ext.autodoc', + 'sphinx.ext.extlinks', + 'sphinx.ext.intersphinx', + 'sphinx.ext.viewcode', +] + +templates_path = ['_templates'] +source_suffix = '.rst' +master_doc = 'index' + +project = 'dpkt' +copyright = '2009-2015 Dug Song and contributors' + +release = get_version('../dpkt/__init__.py') +version = '.'.join(release.split('.')[:2]) + +exclude_patterns = ['_build'] + +pygments_style = 'sphinx' + +modindex_common_prefix = ['dpkt.'] + +autodoc_default_flags = ['members', 'undoc-members', 'inherited-members'] +autodoc_member_order = 'bysource' + + +# -- Options for HTML output -------------------------------------------------- +html_theme = 'default' +html_static_path = ['_static'] + +html_use_modindex = True +html_use_index = True +html_split_index = False +html_show_sourcelink = True + +htmlhelp_basename = 'dpkt' + +# -- Options for extlink extension -------------------------------------------- +extlinks = { + 'issue': ('https://github.com/kbandla/dpkt/issues/%s', '#'), +} diff --git a/docs/contributing.rst b/docs/contributing.rst new file mode 100644 index 0000000..18dcbf6 --- /dev/null +++ b/docs/contributing.rst @@ -0,0 +1,15 @@ +************ +Contributing +************ + +Contributions to dpkt are welcome! Here are some tips to get you started +hacking on dpkt and contributing back your patches. + + +Development setup +================= + + +Submitting changes +================== + diff --git a/docs/examples.rst b/docs/examples.rst new file mode 100644 index 0000000..f983000 --- /dev/null +++ b/docs/examples.rst @@ -0,0 +1,17 @@ + +[@jonoberheide's](https://twitter.com/jonoberheide) old examples still +apply: + +- `dpkt Tutorial #1: ICMP + Echo `__ +- `dpkt Tutorial #2: Parsing a PCAP + File `__ +- `dpkt Tutorial #3: dns + spoofing `__ +- `dpkt Tutorial #4: AS Paths from + MRT/BGP `__ + +`Jeff Silverman `__ has some +`code `__ and +`documentation `__. + diff --git a/docs/index.rst b/docs/index.rst new file mode 100644 index 0000000..ea47651 --- /dev/null +++ b/docs/index.rst @@ -0,0 +1,44 @@ +==== +dpkt +==== +dpkt is a python module for fast, simple packet creation / parsing, with definitions for the basic TCP/IP protocols + +.. include:: badges.rst + +User's guide +============ + +.. toctree:: + :maxdepth: 2 + + installation + quickstart + +Examples +======== +.. include:: examples.rst + +API reference +============= + +.. toctree:: + :maxdepth: 2 + + api/index + + +About +===== + +.. toctree:: + :maxdepth: 2 + + authors + changelog + plans + contributing + +License +======= +.. include:: license.rst + diff --git a/docs/installation.rst b/docs/installation.rst new file mode 100644 index 0000000..f77293a --- /dev/null +++ b/docs/installation.rst @@ -0,0 +1,8 @@ +************ +Installation +************ + + +Installing dpkt +===================== + diff --git a/docs/license.rst b/docs/license.rst new file mode 100644 index 0000000..6b68416 --- /dev/null +++ b/docs/license.rst @@ -0,0 +1,2 @@ + +BSD 3-Clause License, as the upstream project diff --git a/docs/plans.rst b/docs/plans.rst new file mode 100644 index 0000000..a6b1ca3 --- /dev/null +++ b/docs/plans.rst @@ -0,0 +1,13 @@ +***************** +Development plans +***************** + +Current plans +============= + +- Be Awesome + +Future plans +============ + +- Maintain the Awesome diff --git a/docs/quickstart.rst b/docs/quickstart.rst new file mode 100644 index 0000000..3430852 --- /dev/null +++ b/docs/quickstart.rst @@ -0,0 +1,20 @@ +********** +Quickstart +********** + +Grab some packets +================= +Lets first grab some packets:: + + import dpkt + blah + foo + + +Looking at Protocols +==================== +Next lets look at some protocols:: + + import dpkt + blah + foo diff --git a/docs/requirements.txt b/docs/requirements.txt new file mode 100644 index 0000000..2694126 --- /dev/null +++ b/docs/requirements.txt @@ -0,0 +1,2 @@ +mock >= 1.0 +Sphinx >= 1.0 diff --git a/tox.ini b/tox.ini index 3df3ad4..ab0338b 100644 --- a/tox.ini +++ b/tox.ini @@ -1,5 +1,5 @@ [tox] -envlist = py26, py27 +envlist = py26, py27, docs [testenv] install_command = @@ -29,10 +29,7 @@ commands = coveralls [testenv:docs] -changedir=docs/ -deps = - sphinx -commands = - sphinx-build -b linkcheck ./ _build/ - sphinx-build -b html ./ _build/ +changedir=docs +deps = -rdocs/requirements.txt +commands = sphinx-build -b html -d {envtmpdir}/doctrees . {envtmpdir}/html From c015d6e0a31cf75b31d2e650d7d0f3ccbe7f3684 Mon Sep 17 00:00:00 2001 From: Brian Wylie Date: Mon, 18 May 2015 18:38:09 -0600 Subject: [PATCH 2/6] trying to figure our sphinx for auto API still :) --- docs/api/index.rst | 5 ++++- docs/examples.rst | 4 ++++ docs/index.rst | 6 +++++- 3 files changed, 13 insertions(+), 2 deletions(-) diff --git a/docs/api/index.rst b/docs/api/index.rst index 257e683..4d79ec1 100644 --- a/docs/api/index.rst +++ b/docs/api/index.rst @@ -1,4 +1,7 @@ -The dpkt API reference + +DPKT API Reference +================== +The dpkt API reference section is current a large work in progress, please have patience as we fill in the documentation. **Sections** diff --git a/docs/examples.rst b/docs/examples.rst index f983000..1530679 100644 --- a/docs/examples.rst +++ b/docs/examples.rst @@ -1,4 +1,6 @@ +Current DPKG Examples +===================== [@jonoberheide's](https://twitter.com/jonoberheide) old examples still apply: @@ -11,6 +13,8 @@ apply: - `dpkt Tutorial #4: AS Paths from MRT/BGP `__ +Jeff Silverman Docs/Code +======================== `Jeff Silverman `__ has some `code `__ and `documentation `__. diff --git a/docs/index.rst b/docs/index.rst index ea47651..2676f29 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -16,7 +16,11 @@ User's guide Examples ======== -.. include:: examples.rst + +.. toctree:: + :maxdepth: 2 + + examples API reference ============= From e4abe170cc92caf95a4e2b20fca486eb0bf72eec Mon Sep 17 00:00:00 2001 From: Brian Wylie Date: Mon, 18 May 2015 18:46:14 -0600 Subject: [PATCH 3/6] still trying to figure out sphinx :) --- docs/api/index.rst | 4 ++-- docs/examples.rst | 6 ++++-- 2 files changed, 6 insertions(+), 4 deletions(-) diff --git a/docs/api/index.rst b/docs/api/index.rst index 4d79ec1..0123c60 100644 --- a/docs/api/index.rst +++ b/docs/api/index.rst @@ -1,6 +1,6 @@ -DPKT API Reference -================== +API Reference +============= The dpkt API reference section is current a large work in progress, please have patience as we fill in the documentation. **Sections** diff --git a/docs/examples.rst b/docs/examples.rst index 1530679..311ef34 100644 --- a/docs/examples.rst +++ b/docs/examples.rst @@ -1,6 +1,8 @@ +Examples +======== Current DPKG Examples -===================== +--------------------- [@jonoberheide's](https://twitter.com/jonoberheide) old examples still apply: @@ -14,7 +16,7 @@ apply: MRT/BGP `__ Jeff Silverman Docs/Code -======================== +------------------------ `Jeff Silverman `__ has some `code `__ and `documentation `__. From dbe0045e39d66c45441120014a00b18df73275e3 Mon Sep 17 00:00:00 2001 From: Brian Wylie Date: Tue, 19 May 2015 09:26:53 -0600 Subject: [PATCH 4/6] just some tweaks to the documentation --- docs/conf.py | 1 + docs/index.rst | 29 +++++++---------------------- docs/installation.rst | 9 +++------ docs/license.rst | 2 ++ docs/quickstart.rst | 8 ++++---- docs/requirements.txt | 1 + 6 files changed, 18 insertions(+), 32 deletions(-) diff --git a/docs/conf.py b/docs/conf.py index 06a8944..19e04ed 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -35,6 +35,7 @@ extensions = [ 'sphinx.ext.extlinks', 'sphinx.ext.intersphinx', 'sphinx.ext.viewcode', + 'sphinxcontrib.napoleon' ] templates_path = ['_templates'] diff --git a/docs/index.rst b/docs/index.rst index 2676f29..df98bad 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -1,39 +1,27 @@ -==== dpkt ==== +.. include:: badges.rst dpkt is a python module for fast, simple packet creation / parsing, with definitions for the basic TCP/IP protocols -.. include:: badges.rst - -User's guide -============ +Getting Started +=============== .. toctree:: :maxdepth: 2 installation quickstart - -Examples -======== - -.. toctree:: - :maxdepth: 2 - examples -API reference +API Reference ============= - .. toctree:: :maxdepth: 2 api/index - -About -===== - +About dpkt +========== .. toctree:: :maxdepth: 2 @@ -41,8 +29,5 @@ About changelog plans contributing - -License -======= -.. include:: license.rst + license diff --git a/docs/installation.rst b/docs/installation.rst index f77293a..5b85a5e 100644 --- a/docs/installation.rst +++ b/docs/installation.rst @@ -1,8 +1,5 @@ -************ +============ Installation -************ - - -Installing dpkt -===================== +============ +How to install dpkt diff --git a/docs/license.rst b/docs/license.rst index 6b68416..56c7238 100644 --- a/docs/license.rst +++ b/docs/license.rst @@ -1,2 +1,4 @@ +License +======= BSD 3-Clause License, as the upstream project diff --git a/docs/quickstart.rst b/docs/quickstart.rst index 3430852..2213a72 100644 --- a/docs/quickstart.rst +++ b/docs/quickstart.rst @@ -1,9 +1,9 @@ -********** +========== Quickstart -********** +========== Grab some packets -================= +----------------- Lets first grab some packets:: import dpkt @@ -12,7 +12,7 @@ Lets first grab some packets:: Looking at Protocols -==================== +-------------------- Next lets look at some protocols:: import dpkt diff --git a/docs/requirements.txt b/docs/requirements.txt index 2694126..0e91234 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -1,2 +1,3 @@ mock >= 1.0 Sphinx >= 1.0 +sphinxcontrib-napoleon From 7532c9ae4cfd36a57025a14aadc9125725f5ab7c Mon Sep 17 00:00:00 2001 From: Brian Wylie Date: Tue, 19 May 2015 09:50:55 -0600 Subject: [PATCH 5/6] auto generating the api docs --- docs/api/api_auto.rst | 545 ++++++++++++++++++++++++++++++++++++++++++ docs/api/ethernet.rst | 9 - docs/api/http.rst | 15 -- docs/api/index.rst | 8 +- docs/api/ip.rst | 9 - docs/api/tcp.rst | 9 - docs/api/udp.rst | 9 - docs/index.rst | 13 +- 8 files changed, 553 insertions(+), 64 deletions(-) create mode 100644 docs/api/api_auto.rst delete mode 100644 docs/api/ethernet.rst delete mode 100644 docs/api/http.rst delete mode 100644 docs/api/ip.rst delete mode 100644 docs/api/tcp.rst delete mode 100644 docs/api/udp.rst diff --git a/docs/api/api_auto.rst b/docs/api/api_auto.rst new file mode 100644 index 0000000..3837c90 --- /dev/null +++ b/docs/api/api_auto.rst @@ -0,0 +1,545 @@ + +dpkt.ah module +-------------- + +.. automodule:: dpkt.ah + :members: + :undoc-members: + :show-inheritance: + +dpkt.aim module +--------------- + +.. automodule:: dpkt.aim + :members: + :undoc-members: + :show-inheritance: + +dpkt.aoe module +--------------- + +.. automodule:: dpkt.aoe + :members: + :undoc-members: + :show-inheritance: + +dpkt.aoeata module +------------------ + +.. automodule:: dpkt.aoeata + :members: + :undoc-members: + :show-inheritance: + +dpkt.aoecfg module +------------------ + +.. automodule:: dpkt.aoecfg + :members: + :undoc-members: + :show-inheritance: + +dpkt.arp module +--------------- + +.. automodule:: dpkt.arp + :members: + :undoc-members: + :show-inheritance: + +dpkt.asn1 module +---------------- + +.. automodule:: dpkt.asn1 + :members: + :undoc-members: + :show-inheritance: + +dpkt.bgp module +--------------- + +.. automodule:: dpkt.bgp + :members: + :undoc-members: + :show-inheritance: + +dpkt.cdp module +--------------- + +.. automodule:: dpkt.cdp + :members: + :undoc-members: + :show-inheritance: + +dpkt.crc32c module +------------------ + +.. automodule:: dpkt.crc32c + :members: + :undoc-members: + :show-inheritance: + +dpkt.decorators module +---------------------- + +.. automodule:: dpkt.decorators + :members: + :undoc-members: + :show-inheritance: + +dpkt.dhcp module +---------------- + +.. automodule:: dpkt.dhcp + :members: + :undoc-members: + :show-inheritance: + +dpkt.diameter module +-------------------- + +.. automodule:: dpkt.diameter + :members: + :undoc-members: + :show-inheritance: + +dpkt.dns module +--------------- + +.. automodule:: dpkt.dns + :members: + :undoc-members: + :show-inheritance: + +dpkt.dpkt module +---------------- + +.. automodule:: dpkt.dpkt + :members: + :undoc-members: + :show-inheritance: + +dpkt.dtp module +--------------- + +.. automodule:: dpkt.dtp + :members: + :undoc-members: + :show-inheritance: + +dpkt.esp module +--------------- + +.. automodule:: dpkt.esp + :members: + :undoc-members: + :show-inheritance: + +dpkt.ethernet module +-------------------- + +.. automodule:: dpkt.ethernet + :members: + :undoc-members: + :show-inheritance: + +dpkt.gre module +--------------- + +.. automodule:: dpkt.gre + :members: + :undoc-members: + :show-inheritance: + +dpkt.gzip module +---------------- + +.. automodule:: dpkt.gzip + :members: + :undoc-members: + :show-inheritance: + +dpkt.h225 module +---------------- + +.. automodule:: dpkt.h225 + :members: + :undoc-members: + :show-inheritance: + +dpkt.hsrp module +---------------- + +.. automodule:: dpkt.hsrp + :members: + :undoc-members: + :show-inheritance: + +dpkt.http module +---------------- + +.. automodule:: dpkt.http + :members: + :undoc-members: + :show-inheritance: + +dpkt.icmp module +---------------- + +.. automodule:: dpkt.icmp + :members: + :undoc-members: + :show-inheritance: + +dpkt.icmp6 module +----------------- + +.. automodule:: dpkt.icmp6 + :members: + :undoc-members: + :show-inheritance: + +dpkt.ieee80211 module +--------------------- + +.. automodule:: dpkt.ieee80211 + :members: + :undoc-members: + :show-inheritance: + +dpkt.igmp module +---------------- + +.. automodule:: dpkt.igmp + :members: + :undoc-members: + :show-inheritance: + +dpkt.ip module +-------------- + +.. automodule:: dpkt.ip + :members: + :undoc-members: + :show-inheritance: + +dpkt.ip6 module +--------------- + +.. automodule:: dpkt.ip6 + :members: + :undoc-members: + :show-inheritance: + +dpkt.ipx module +--------------- + +.. automodule:: dpkt.ipx + :members: + :undoc-members: + :show-inheritance: + +dpkt.llc module +--------------- + +.. automodule:: dpkt.llc + :members: + :undoc-members: + :show-inheritance: + +dpkt.loopback module +-------------------- + +.. automodule:: dpkt.loopback + :members: + :undoc-members: + :show-inheritance: + +dpkt.mrt module +--------------- + +.. automodule:: dpkt.mrt + :members: + :undoc-members: + :show-inheritance: + +dpkt.netbios module +------------------- + +.. automodule:: dpkt.netbios + :members: + :undoc-members: + :show-inheritance: + +dpkt.netflow module +------------------- + +.. automodule:: dpkt.netflow + :members: + :undoc-members: + :show-inheritance: + +dpkt.ntp module +--------------- + +.. automodule:: dpkt.ntp + :members: + :undoc-members: + :show-inheritance: + +dpkt.ospf module +---------------- + +.. automodule:: dpkt.ospf + :members: + :undoc-members: + :show-inheritance: + +dpkt.pcap module +---------------- + +.. automodule:: dpkt.pcap + :members: + :undoc-members: + :show-inheritance: + +dpkt.pim module +--------------- + +.. automodule:: dpkt.pim + :members: + :undoc-members: + :show-inheritance: + +dpkt.pmap module +---------------- + +.. automodule:: dpkt.pmap + :members: + :undoc-members: + :show-inheritance: + +dpkt.ppp module +--------------- + +.. automodule:: dpkt.ppp + :members: + :undoc-members: + :show-inheritance: + +dpkt.pppoe module +----------------- + +.. automodule:: dpkt.pppoe + :members: + :undoc-members: + :show-inheritance: + +dpkt.qq module +-------------- + +.. automodule:: dpkt.qq + :members: + :undoc-members: + :show-inheritance: + +dpkt.radiotap module +-------------------- + +.. automodule:: dpkt.radiotap + :members: + :undoc-members: + :show-inheritance: + +dpkt.radius module +------------------ + +.. automodule:: dpkt.radius + :members: + :undoc-members: + :show-inheritance: + +dpkt.rfb module +--------------- + +.. automodule:: dpkt.rfb + :members: + :undoc-members: + :show-inheritance: + +dpkt.rip module +--------------- + +.. automodule:: dpkt.rip + :members: + :undoc-members: + :show-inheritance: + +dpkt.rpc module +--------------- + +.. automodule:: dpkt.rpc + :members: + :undoc-members: + :show-inheritance: + +dpkt.rtp module +--------------- + +.. automodule:: dpkt.rtp + :members: + :undoc-members: + :show-inheritance: + +dpkt.rx module +-------------- + +.. automodule:: dpkt.rx + :members: + :undoc-members: + :show-inheritance: + +dpkt.sccp module +---------------- + +.. automodule:: dpkt.sccp + :members: + :undoc-members: + :show-inheritance: + +dpkt.sctp module +---------------- + +.. automodule:: dpkt.sctp + :members: + :undoc-members: + :show-inheritance: + +dpkt.sip module +--------------- + +.. automodule:: dpkt.sip + :members: + :undoc-members: + :show-inheritance: + +dpkt.sll module +--------------- + +.. automodule:: dpkt.sll + :members: + :undoc-members: + :show-inheritance: + +dpkt.smb module +--------------- + +.. automodule:: dpkt.smb + :members: + :undoc-members: + :show-inheritance: + +dpkt.snoop module +----------------- + +.. automodule:: dpkt.snoop + :members: + :undoc-members: + :show-inheritance: + +dpkt.ssl module +--------------- + +.. automodule:: dpkt.ssl + :members: + :undoc-members: + :show-inheritance: + +dpkt.ssl_ciphersuites module +---------------------------- + +.. automodule:: dpkt.ssl_ciphersuites + :members: + :undoc-members: + :show-inheritance: + +dpkt.stp module +--------------- + +.. automodule:: dpkt.stp + :members: + :undoc-members: + :show-inheritance: + +dpkt.stun module +---------------- + +.. automodule:: dpkt.stun + :members: + :undoc-members: + :show-inheritance: + +dpkt.tcp module +--------------- + +.. automodule:: dpkt.tcp + :members: + :undoc-members: + :show-inheritance: + +dpkt.telnet module +------------------ + +.. automodule:: dpkt.telnet + :members: + :undoc-members: + :show-inheritance: + +dpkt.tftp module +---------------- + +.. automodule:: dpkt.tftp + :members: + :undoc-members: + :show-inheritance: + +dpkt.tns module +--------------- + +.. automodule:: dpkt.tns + :members: + :undoc-members: + :show-inheritance: + +dpkt.tpkt module +---------------- + +.. automodule:: dpkt.tpkt + :members: + :undoc-members: + :show-inheritance: + +dpkt.udp module +--------------- + +.. automodule:: dpkt.udp + :members: + :undoc-members: + :show-inheritance: + +dpkt.vrrp module +---------------- + +.. automodule:: dpkt.vrrp + :members: + :undoc-members: + :show-inheritance: + +dpkt.yahoo module +----------------- + +.. automodule:: dpkt.yahoo + :members: + :undoc-members: + :show-inheritance: + diff --git a/docs/api/ethernet.rst b/docs/api/ethernet.rst deleted file mode 100644 index fb2c05f..0000000 --- a/docs/api/ethernet.rst +++ /dev/null @@ -1,9 +0,0 @@ -******** -Ethernet -******** - -.. module:: dpkt.ethernet - -.. autoclass:: Ethernet - :members: - diff --git a/docs/api/http.rst b/docs/api/http.rst deleted file mode 100644 index f03b842..0000000 --- a/docs/api/http.rst +++ /dev/null @@ -1,15 +0,0 @@ -**** -HTTP -**** - -.. module:: dpkt.http - -.. autoclass:: Message - :members: - -.. autoclass:: Request - :members: - -.. autoclass:: Response - :members: - diff --git a/docs/api/index.rst b/docs/api/index.rst index 0123c60..5975dd5 100644 --- a/docs/api/index.rst +++ b/docs/api/index.rst @@ -6,10 +6,6 @@ The dpkt API reference section is current a large work in progress, please have **Sections** .. toctree:: - :maxdepth: 1 + :maxdepth: 4 - ethernet - ip - udp - tcp - http + api_auto diff --git a/docs/api/ip.rst b/docs/api/ip.rst deleted file mode 100644 index f40a30b..0000000 --- a/docs/api/ip.rst +++ /dev/null @@ -1,9 +0,0 @@ -** -IP -** - -.. module:: dpkt.ip - -.. autoclass:: IP - :members: - diff --git a/docs/api/tcp.rst b/docs/api/tcp.rst deleted file mode 100644 index 500b33f..0000000 --- a/docs/api/tcp.rst +++ /dev/null @@ -1,9 +0,0 @@ -*** -TCP -*** - -.. module:: dpkt.tcp - -.. autoclass:: TCP - :members: - diff --git a/docs/api/udp.rst b/docs/api/udp.rst deleted file mode 100644 index 8f30364..0000000 --- a/docs/api/udp.rst +++ /dev/null @@ -1,9 +0,0 @@ -*** -UDP -*** - -.. module:: dpkt.udp - -.. autoclass:: UDP - :members: - diff --git a/docs/index.rst b/docs/index.rst index df98bad..cddb898 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -13,13 +13,6 @@ Getting Started quickstart examples -API Reference -============= -.. toctree:: - :maxdepth: 2 - - api/index - About dpkt ========== .. toctree:: @@ -31,3 +24,9 @@ About dpkt contributing license +API Reference +============= +.. toctree:: + :maxdepth: 2 + + api/index From 698cf787c0b7ac6db21ab3b5fe006fbac008824a Mon Sep 17 00:00:00 2001 From: Brian Wylie Date: Tue, 19 May 2015 12:02:58 -0600 Subject: [PATCH 6/6] some doc reorg and a contributing section --- CONTRIBUTING.rst | 45 +++++++++++++++++++++++++++++++++++++++++++ docs/api/index.rst | 4 ++-- docs/contributing.rst | 16 +-------------- docs/index.rst | 13 +++++++------ 4 files changed, 55 insertions(+), 23 deletions(-) create mode 100644 CONTRIBUTING.rst diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst new file mode 100644 index 0000000..cee82e8 --- /dev/null +++ b/CONTRIBUTING.rst @@ -0,0 +1,45 @@ +============ +Contributing +============ + +Report a Bug or Make a Feature Request +-------------------------------------- +Please go to the GitHub Issues page: https://github.com/kbandla/dpkt/issues. + +Checkout the Code +---------------- + +:: + + git clone https://github.com/kblandla/dpkt.git + + +Become a Developer +------------------ +dpkt uses the 'GitHub Flow' model: `GitHub Flow `_ + +- To work on something new, create a descriptively named branch off of master (ie: my-awesome) +- Commit to that branch locally and regularly push your work to the same named branch on the server +- When you need feedback or help, or you think the branch is ready for merging, open a pull request +- After someone else has reviewed and signed off on the feature, you can merge it into master + +Getting Started +~~~~~~~~~~~~~~~ + - Fork the repo on GitHub + - git clone git@github.com:your_name_here/dpkt.git + +New Feature or Bug +~~~~~~~~~~~~~~~~~~ + + :: + + $ git checkout -b my-awesome + $ git push -u origin my-awesome + $ ; git push + $ ; git push + $ tox (this will run all the tests) + + - Go to github and hit 'New pull request' + - Someone reviews it and says 'AOK' + - Merge the pull request (green button) + diff --git a/docs/api/index.rst b/docs/api/index.rst index 5975dd5..7d44785 100644 --- a/docs/api/index.rst +++ b/docs/api/index.rst @@ -1,9 +1,9 @@ API Reference ============= -The dpkt API reference section is current a large work in progress, please have patience as we fill in the documentation. +The dpkt API reference section is currently a work in progress, please have patience as we fill in and improve the documentation. -**Sections** +**dpkt Modules** .. toctree:: :maxdepth: 4 diff --git a/docs/contributing.rst b/docs/contributing.rst index 18dcbf6..3bdd7dc 100644 --- a/docs/contributing.rst +++ b/docs/contributing.rst @@ -1,15 +1 @@ -************ -Contributing -************ - -Contributions to dpkt are welcome! Here are some tips to get you started -hacking on dpkt and contributing back your patches. - - -Development setup -================= - - -Submitting changes -================== - +.. include:: ../CONTRIBUTING.rst \ No newline at end of file diff --git a/docs/index.rst b/docs/index.rst index cddb898..9d28965 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -13,6 +13,13 @@ Getting Started quickstart examples +API Reference +============= +.. toctree:: + :maxdepth: 1 + + api/index + About dpkt ========== .. toctree:: @@ -24,9 +31,3 @@ About dpkt contributing license -API Reference -============= -.. toctree:: - :maxdepth: 2 - - api/index