20 files changed, 949 insertions, 0 deletions
diff --git a/docs/source/api.rst b/docs/source/api.rst
new file mode 100644
index 0000000..d2fd54d
--- /dev/null
+++ b/docs/source/api.rst
@@ -0,0 +1,274 @@
+=============
+API Reference
+=============
+
+This page documents netaddr's public API. Only things explicitly mentioned in this documentation
+are supported and considered part of the public API.
+
+Any of the following is considered private and unsupported:
+
+* Anything within any of the ``netaddr`` submodules (``from netaddr.X import Y``)
+* Anything with a name started with a single underscore (``_X``)
+* Anything not explicitly documented as part of the public API
+
+------------------
+IP Class Hierarchy
+------------------
+
+Here the class hierarchy for IP related classes ::
+
+     +---------+                                                +---------+
+     | ipv4(M) |                                                | ipv6(M) |
+     +---------+                                                +---------+
+          |                                                          |
+       (HAS A)                                                    (HAS A)
+          |                                                          |
+          +-----+----------------+-----------------+                 |
+                |       +--------|-------+---------|--------+--------+
+                |       |        |       |         |        |
+                |       |        |       |         |        |
+                v       v        v       v         |        |
+              +-----------+    +-----------+       |        |
+              | IPAddress |    | IPNetwork |       |        |
+              +-----------+    +-----------+       |        |
+                    |                |             |        |
+                 (HAS A)          (HAS A)          |        |
+                    |                |             v        v
+                    +-------+--------+           +------------+
+                            |                    |  IPRange   |
+                            |                    +------------+
+                            v                          |
+                        +-------+                      |
+                        | IPSet |                      v
+                        +-------+                  +--------+
+                                                   | IPGlob |
+                                                   +--------+
+
+
+---------
+Constants
+---------
+
+The following constants are used by the various *flags* arguments on netaddr class constructors.
+
+.. data:: netaddr.P
+          netaddr.INET_PTON
+
+   Use inet_pton() semantics instead of inet_aton() when parsing IPv4.
+
+   See the :meth:`IPAddress.__init__` documentation for details.
+
+   .. versionchanged:: 0.10.0
+        This parsing mode will become stricter in the future and it will reject leading zeros.
+
+.. data:: netaddr.INET_ATON
+
+    Use ``inet_aton()`` semantics when parsing IPv4.
+
+    See the :meth:`IPAddress.__init__` documentation for details.
+
+    .. versionadded:: 0.10.0
+
+.. data:: netaddr.Z
+          netaddr.ZEROFILL
+
+   Remove any preceding zeros from IPv4 address octets before parsing.
+
+   See the :meth:`IPAddress.__init__` documentation for details.
+
+.. data:: netaddr.N
+          netaddr.NOHOST
+
+   Remove any host bits found to the right of an applied CIDR prefix.
+
+   See the :meth:`IPNetwork.__init__` documentation for details.
+
+-----------------
+Custom Exceptions
+-----------------
+.. autoexception:: netaddr.AddrConversionError
+    :exclude-members: __init__
+
+.. autoexception:: netaddr.AddrFormatError
+    :exclude-members: __init__
+
+.. autoexception:: netaddr.NotRegisteredError
+    :exclude-members: __init__
+
+------------
+IP addresses
+------------
+
+An IP address is a virtual address used to identify the source and destination of (layer 3) packets being transferred between hosts in a switched network. This library fully supports both IPv4 and the new IPv6 standards.
+
+The `IPAddress` class is used to identify individual IP addresses.
+
+.. autoclass:: netaddr.IPAddress
+    :members:
+    :inherited-members:
+
+.. _ipv6_formatting_dialects:
+
+^^^^^^^^^^^^^^^^^^^^^^^^
+IPv6 formatting dialects
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+The following dialect classes can be used with the IPAddress.format method.
+
+.. autoclass:: netaddr.ipv6_compact
+    :members:
+
+.. autoclass:: netaddr.ipv6_full
+    :members:
+
+.. autoclass:: netaddr.ipv6_verbose
+    :members:
+
+-----------------------
+IP networks and subnets
+-----------------------
+
+The `IPNetwork` class is used to represent a group of IP addresses that comprise a network/subnet/VLAN containing hosts.
+
+Nowadays, IP networks are usually specified using the CIDR format with a prefix indicating the size of the netmask. In the real world, there are a number of ways to express a "network"" and so the flexibility of the `IPNetwork` class constructor reflects this.
+
+.. autoclass:: netaddr.IPNetwork
+    :members:
+
+---------------------------
+Arbitrary IP address ranges
+---------------------------
+
+netaddr was designed to accommodate the many different ways in which groups of IP addresses and IP networks are specified, not only in router configurations but also less standard but more human-readable forms found in, for instance, configuration files.
+
+Here are the options currently available.
+
+^^^^^^^^^^^^^^
+bounded ranges
+^^^^^^^^^^^^^^
+
+A bounded range is a group of IP addresses specified using a start and end address forming a contiguous block. No bit boundaries are assumed but the end address must be numerically greater than or equal to the start address.
+
+.. autoclass:: netaddr.IPRange
+    :members:
+
+^^^^^^^^^^^^^^
+IP glob ranges
+^^^^^^^^^^^^^^
+
+A very useful way to represent IP network in configuration files and on the command line for those who do not speak CIDR.
+
+The `IPGlob` class is used to represent individual glob ranges.
+
+.. autoclass:: netaddr.IPGlob
+    :members:
+
+^^^^^^^^^^^^^^^^^^
+globbing functions
+^^^^^^^^^^^^^^^^^^
+
+It is also very useful to be able to convert between glob ranges and CIDR and IP ranges. The following function enable these various conversions.
+
+.. autofunction:: netaddr.cidr_to_glob
+.. autofunction:: netaddr.glob_to_cidrs
+.. autofunction:: netaddr.glob_to_iprange
+.. autofunction:: netaddr.glob_to_iptuple
+.. autofunction:: netaddr.iprange_to_globs
+
+^^^^^^^^^^^^^^^
+``nmap`` ranges
+^^^^^^^^^^^^^^^
+
+``nmap`` is a well known network security tool. It has a particularly flexible way of specifying IP address groupings.
+
+Functions are provided that allow the verification and enumeration of IP address specified in this format.
+
+.. autofunction:: netaddr.valid_nmap_range
+.. autofunction:: netaddr.iter_nmap_range
+
+-------
+IP sets
+-------
+
+When dealing with large numbers of IP addresses and ranges it is often useful to manipulate them as sets so you can calculate intersections, unions and differences between various groups of them.
+
+The `IPSet` class was built specifically for this purpose.
+
+.. autoclass:: netaddr.IPSet
+    :members:
+
+---------------------------
+IP functions and generators
+---------------------------
+
+The following are a set of useful helper functions related to the various format supported in this library.
+
+.. autofunction:: netaddr.all_matching_cidrs
+.. autofunction:: netaddr.cidr_abbrev_to_verbose
+.. autofunction:: netaddr.cidr_exclude
+.. autofunction:: netaddr.cidr_merge
+.. autofunction:: netaddr.iprange_to_cidrs
+.. autofunction:: netaddr.iter_iprange
+.. autofunction:: netaddr.iter_unique_ips
+.. autofunction:: netaddr.largest_matching_cidr
+.. autofunction:: netaddr.smallest_matching_cidr
+.. autofunction:: netaddr.spanning_cidr
+
+---------------------------------------
+MAC addresses and the IEEE EUI standard
+---------------------------------------
+
+A MAC address is the 48-bit hardware address associated with a particular physical interface on a networked host. They are found in all networked devices and serve to identify (layer 2) frames in the networking stack.
+
+The `EUI` class is used to represents MACs (as well as their larger and less common 64-bit cousins).
+
+.. autoclass:: netaddr.EUI
+    :members:
+
+.. autoclass:: netaddr.OUI
+    :members:
+
+.. autoclass:: netaddr.IAB
+    :members:
+
+.. _mac_formatting_dialects:
+
+^^^^^^^^^^^^^^^^^^^^^^^
+MAC formatting dialects
+^^^^^^^^^^^^^^^^^^^^^^^
+
+The following dialects are used to specify the formatting of MAC addresses.
+
+.. autoclass:: netaddr.mac_bare
+    :members:
+
+.. autoclass:: netaddr.mac_cisco
+    :members:
+
+.. autoclass:: netaddr.mac_eui48
+    :members:
+
+.. autoclass:: netaddr.mac_pgsql
+    :members:
+
+.. autoclass:: netaddr.mac_unix
+    :members:
+
+--------------------
+Validation functions
+--------------------
+.. autofunction:: netaddr.valid_ipv4
+.. autofunction:: netaddr.valid_ipv6
+.. autofunction:: netaddr.valid_glob
+.. autofunction:: netaddr.valid_mac
+
+------------
+A bit of fun
+------------
+
+Who said networking was all about being serious? It's always good to lighten up and have a bit of fun.
+
+Let's face it, no networking library worth its salt would be complete without support for RFC 1924 - http://www.ietf.org/rfc/rfc1924 ``:-)``
+
+.. autofunction:: netaddr.base85_to_ipv6
+.. autofunction:: netaddr.ipv6_to_base85
diff --git a/docs/source/authors.rst b/docs/source/authors.rst
new file mode 100644
index 0000000..670766d
--- /dev/null
+++ b/docs/source/authors.rst
@@ -0,0 +1,5 @@
+=======
+Authors
+=======
+
+.. include:: ../../AUTHORS
diff --git a/docs/source/changes.rst b/docs/source/changes.rst
new file mode 100644
index 0000000..1556462
--- /dev/null
+++ b/docs/source/changes.rst
@@ -0,0 +1,5 @@
+=========
+Changelog
+=========
+
+.. include:: ../../CHANGELOG
diff --git a/docs/source/conf.py b/docs/source/conf.py
new file mode 100644
index 0000000..23a513c
--- /dev/null
+++ b/docs/source/conf.py
@@ -0,0 +1,270 @@
+# -*- coding: utf-8 -*-
+#
+# netaddr documentation build configuration file, created by
+# sphinx-quickstart on Sun May 27 22:23:51 2012.
+#
+# This file is execfile()d with the current directory set to its containing dir.
+#
+# Note that not all possible configuration values are present in this
+# autogenerated file.
+#
+# All configuration values have a default; values that are commented out
+# serve to show the default.
+
+import sys, os
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+#sys.path.insert(0, os.path.abspath('.'))
+
+# -- General configuration -----------------------------------------------------
+
+# If your documentation needs a minimal Sphinx version, state it here.
+#needs_sphinx = '1.0'
+
+# Add any Sphinx extension module names here, as strings. They can be extensions
+# coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
+extensions = ['sphinx.ext.autodoc', 'sphinx.ext.doctest', 'sphinx.ext.todo', 'sphinx.ext.coverage', 'sphinx.ext.viewcode']
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['_templates']
+
+# The suffix of source filenames.
+source_suffix = '.rst'
+
+# The encoding of source files.
+#source_encoding = 'utf-8-sig'
+
+# The master toctree document.
+master_doc = 'index'
+
+# General information about the project.
+project = u'netaddr'
+copyright = u'Copyright (c) 2008 by David P. D. Moss. All rights reserved.'
+
+# The version info for the project you're documenting, acts as replacement for
+# |version| and |release|, also used in various other places throughout the
+# built documents.
+#
+# The short X.Y version.
+version = '0.10.1'
+# The full version, including alpha/beta/rc tags.
+release = '0.10.1'
+
+# The language for content autogenerated by Sphinx. Refer to documentation
+# for a list of supported languages.
+#language = None
+
+# There are two options for replacing |today|: either, you set today to some
+# non-false value, then it is used:
+#today = ''
+# Else, today_fmt is used as the format for a strftime call.
+#today_fmt = '%B %d, %Y'
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+exclude_patterns = []
+
+# The reST default role (used for this markup: `text`) to use for all documents.
+#default_role = None
+
+# If true, '()' will be appended to :func: etc. cross-reference text.
+#add_function_parentheses = True
+
+# If true, the current module name will be prepended to all description
+# unit titles (such as .. function::).
+#add_module_names = True
+
+# If true, sectionauthor and moduleauthor directives will be shown in the
+# output. They are ignored by default.
+#show_authors = False
+
+# The name of the Pygments (syntax highlighting) style to use.
+pygments_style = 'sphinx'
+
+# A list of ignored prefixes for module index sorting.
+#modindex_common_prefix = []
+
+
+# -- Options for HTML output ---------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+html_theme = 'furo'
+
+# Theme options are theme-specific and customize the look and feel of a theme
+# further.  For a list of options available for each theme, see the
+# documentation.
+#html_theme_options = {}
+
+# Add any paths that contain custom themes here, relative to this directory.
+#html_theme_path = []
+
+# The name for this set of Sphinx documents.  If None, it defaults to
+# "<project> v<release> documentation".
+#html_title = None
+
+# A shorter title for the navigation bar.  Default is the same as html_title.
+#html_short_title = None
+
+# The name of an image file (relative to this directory) to place at the top
+# of the sidebar.
+#html_logo = None
+
+# The name of an image file (within the static path) to use as favicon of the
+# docs.  This file should be a Windows icon file (.ico) being 16x16 or 32x32
+# pixels large.
+#html_favicon = None
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path = ['static']
+
+# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
+# using the given strftime format.
+#html_last_updated_fmt = '%b %d, %Y'
+
+# If true, SmartyPants will be used to convert quotes and dashes to
+# typographically correct entities.
+#html_use_smartypants = True
+
+# Custom sidebar templates, maps document names to template names.
+#html_sidebars = {}
+
+# Additional templates that should be rendered to pages, maps page names to
+# template names.
+#html_additional_pages = {}
+
+# If false, no module index is generated.
+#html_domain_indices = True
+
+# If false, no index is generated.
+#html_use_index = True
+
+# If true, the index is split into individual pages for each letter.
+#html_split_index = False
+
+# If true, links to the reST sources are added to the pages.
+#html_show_sourcelink = True
+
+# If true, "Created using Sphinx" is shown in the HTML footer. Default is True.
+#html_show_sphinx = True
+
+# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True.
+#html_show_copyright = True
+
+# If true, an OpenSearch description file will be output, and all pages will
+# contain a <link> tag referring to it.  The value of this option must be the
+# base URL from which the finished HTML is served.
+#html_use_opensearch = ''
+
+# This is the file name suffix for HTML files (e.g. ".xhtml").
+#html_file_suffix = None
+
+# Output file base name for HTML help builder.
+htmlhelp_basename = 'netaddrdoc'
+
+
+# -- Options for LaTeX output --------------------------------------------------
+
+latex_elements = {
+# The paper size ('letterpaper' or 'a4paper').
+#'papersize': 'letterpaper',
+
+# The font size ('10pt', '11pt' or '12pt').
+#'pointsize': '10pt',
+
+# Additional stuff for the LaTeX preamble.
+#'preamble': '',
+}
+
+# Grouping the document tree into LaTeX files. List of tuples
+# (source start file, target name, title, author, documentclass [howto/manual]).
+latex_documents = [
+  ('index', 'netaddr.tex', u'netaddr Documentation',
+   u'David P. D. Moss', 'manual'),
+]
+
+# The name of an image file (relative to this directory) to place at the top of
+# the title page.
+#latex_logo = None
+
+# For "manual" documents, if this is true, then toplevel headings are parts,
+# not chapters.
+#latex_use_parts = False
+
+# If true, show page references after internal links.
+#latex_show_pagerefs = False
+
+# If true, show URL addresses after external links.
+#latex_show_urls = False
+
+# Documents to append as an appendix to all manuals.
+#latex_appendices = []
+
+# If false, no module index is generated.
+#latex_domain_indices = True
+
+
+# -- Options for manual page output --------------------------------------------
+
+# One entry per manual page. List of tuples
+# (source start file, name, description, authors, manual section).
+man_pages = [
+    ('index', 'netaddr', u'netaddr Documentation',
+     [u'David P. D. Moss'], 1)
+]
+
+# If true, show URL addresses after external links.
+#man_show_urls = False
+
+
+# -- Options for Texinfo output ------------------------------------------------
+
+# Grouping the document tree into Texinfo files. List of tuples
+# (source start file, target name, title, author,
+#  dir menu entry, description, category)
+texinfo_documents = [
+  ('index',
+   'netaddr',
+   u'netaddr Documentation',
+   u'David P. D. Moss',
+   'netaddr',
+   'A network address manipulation library for Python',
+   'Miscellaneous'),
+]
+
+# Documents to append as an appendix to all manuals.
+#texinfo_appendices = []
+
+# If false, no module index is generated.
+#texinfo_domain_indices = True
+
+# How to display URL addresses: 'footnote', 'no', or 'inline'.
+#texinfo_show_urls = 'footnote'
+
+# Warn about invalid references
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-nitpicky
+nitpicky = True
+
+#autodoc_class_signature = 'separated'
+
+autodoc_default_options = {
+    'special-members': '__init__',
+}
+
+
+html_css_files = ['custom.css']
+
+rst_prolog = """
+.. |iana_special_ipv4| replace:: `IANA IPv4 Special-Purpose Address Registry`_
+.. |iana_special_ipv6| replace:: `IANA IPv6 Special-Purpose Address Registry`_
+.. _IANA IPv4 Special-Purpose Address Registry: https://www.iana.org/assignments/iana-ipv4-special-registry/iana-ipv4-special-registry.xhtml
+.. _IANA IPv6 Special-Purpose Address Registry: https://www.iana.org/assignments/iana-ipv6-special-registry/iana-ipv6-special-registry.xhtml
+
+.. |ipv4_in_ipv6_handling| replace:: There is no special handling of IPv4-mapped IPv6 addresses \
+(``::ffff:0:0/96``, RFC 4291). If you need to treat them as if they were their IPv4 counterparts \
+take a look at the :meth:`~netaddr.IPAddress.to_canonical` method.
+"""
diff --git a/docs/source/contributors.rst b/docs/source/contributors.rst
new file mode 100644
index 0000000..7d3758e
--- /dev/null
+++ b/docs/source/contributors.rst
@@ -0,0 +1,5 @@
+============
+Contributors
+============
+
+.. include:: ../../THANKS
diff --git a/docs/source/copyright.rst b/docs/source/copyright.rst
new file mode 100644
index 0000000..5ed6b2c
--- /dev/null
+++ b/docs/source/copyright.rst
@@ -0,0 +1,5 @@
+=========
+Copyright
+=========
+
+.. include:: ../../COPYRIGHT
diff --git a/docs/source/dev-how-to/index.rst b/docs/source/dev-how-to/index.rst
new file mode 100644
index 0000000..a432cc5
--- /dev/null
+++ b/docs/source/dev-how-to/index.rst
@@ -0,0 +1,7 @@
+How-to guides
+=============
+
+.. toctree::
+    :maxdepth: 1
+
+    release
diff --git a/docs/source/dev-how-to/release.rst b/docs/source/dev-how-to/release.rst
new file mode 100644
index 0000000..d875c39
--- /dev/null
+++ b/docs/source/dev-how-to/release.rst
@@ -0,0 +1,58 @@
+----------------------
+How to release netaddr
+----------------------
+
+Here is how to go about releasing a new version of `netaddr`.
+
+* Make sure you have the necessary dependencies installed:
+
+  ::
+
+    pip install --upgrade wheel twine
+
+* Pull down the latest set of changes for the ``master`` branch.
+
+  The assumption is the ``master`` branch build is green and everything works correctly
+  (we have a CI process in place).
+
+* Update the top-most section in the CHANGELOG with details of all notable
+  changes since the last release that aren't there already.
+
+  Set the release date to the current day.
+
+* Decide what the new version should be (depending on the changes that will be present
+  in this release):
+
+  * Fixes – patch version bump
+  * New features – minor version bump
+  * Substantial or breaking changes – major version bump
+
+* Update the version numbers throughout the source code. That includes changing the currently
+  version number in
+
+  - netaddr/__init__.py
+  - docs/source/conf.py
+
+  and replacing all ``NEXT_NETADDR_VERSION`` instances with the new version (except for places
+  like this file, of course).
+
+* Commit all changes.
+
+* Build the packages and documentation.
+
+    `make dist`
+
+* Upload all built packages to PyPI (currently drkjam and jstasiak can do this)::
+
+    twine upload dist/*
+
+* Tag the release and sync it to remote repo.
+
+    `git tag -a x.y.z -m 'Release version x.y.z'`
+    `make push_tags`
+
+* Create a `GitHub Release <https://github.com/netaddr/netaddr/releases/new>`_ based on
+  the tag you just pushed.
+
+  Put the new ``CHANGELOG`` contents there and add the "Full changelog" link at the
+  end (copy and adapt from the previous release).
diff --git a/docs/source/how-to.rst b/docs/source/how-to.rst
new file mode 100644
index 0000000..ed151d3
--- /dev/null
+++ b/docs/source/how-to.rst
@@ -0,0 +1,9 @@
+How-to guides
+=============
+
+The pages in this section are recipes and provide steps to address common problems and use-cases.
+
+.. toctree::
+    :maxdepth: 1
+
+    installation
diff --git a/docs/source/index.rst b/docs/source/index.rst
new file mode 100644
index 0000000..8255518
--- /dev/null
+++ b/docs/source/index.rst
@@ -0,0 +1,41 @@
+=====================
+netaddr documentation
+=====================
+
+A Python library for representing and manipulating layer 3 (IP) and layer 2 (MAC)
+network addresses.
+
+netaddr's documentation uses the `Diátaxis approach to technical documentation
+authoring <https://diataxis.fr/>`_ and is organized like so:
+
+* :doc:`tutorials` take you on a step-by-step journey through some of the netaddr's features.
+  Start here if you're new to netaddr.
+* :doc:`how-to` are recipes and provide steps to address common problems and use-cases.
+* :doc:`reference` contains technical description of various parts of netaddr machinery
+  (including the :doc:`api`).
+
+.. toctree::
+    :maxdepth: 1
+    :hidden:
+    :caption: User documentation
+
+    tutorials
+    how-to
+    reference
+    authors
+    contributors
+
+.. toctree::
+    :maxdepth: 1
+    :hidden:
+    :caption: Developer documentation
+
+    dev-how-to/index
+
+------------------
+Indices and tables
+------------------
+
+* :ref:`genindex`
+* :ref:`search`
+
diff --git a/docs/source/installation.rst b/docs/source/installation.rst
new file mode 100644
index 0000000..e468331
--- /dev/null
+++ b/docs/source/installation.rst
@@ -0,0 +1,45 @@
+======================
+How to install netaddr
+======================
+
+netaddr is available in various formats :
+
+- source code repository
+- source distribution packages (tarball and zip formats)
+- Python universal wheel packages
+
+Various Linux distributions make it available via their package managers.
+
+---------------------
+Locating the software
+---------------------
+
+The netaddr project is hosted here on github
+
+    https://github.com/drkjam/netaddr/
+
+----------------------------------------
+Installing from the Python Package Index
+----------------------------------------
+
+The easiest way to install netaddr is to use pip.
+
+Download and install the latest version from PyPI -
+https://pypi.org/project/pip and run the following command ::
+
+    pip install netaddr
+
+--------------------------------
+Installing from a source package
+--------------------------------
+
+Download the latest release tarball/zip file and extract it to a temporary
+directory or clone the repository into a local working directory.
+
+Run the setup file from directory::
+
+    python setup.py install
+
+This automatically places the required files in the ``lib/site-packages``
+directory of the Python version you used to run the setup script, may
+also be part of a virtualenv or similar environment manager.
diff --git a/docs/source/license.rst b/docs/source/license.rst
new file mode 100644
index 0000000..98f7849
--- /dev/null
+++ b/docs/source/license.rst
@@ -0,0 +1,5 @@
+=======
+License
+=======
+
+.. include:: ../../LICENSE
diff --git a/docs/source/reference.rst b/docs/source/reference.rst
new file mode 100644
index 0000000..b8107e7
--- /dev/null
+++ b/docs/source/reference.rst
@@ -0,0 +1,33 @@
+Reference
+=========
+
+The pages in this section contain technical description of various parts of netaddr machinery.
+
+netaddr provides support for:
+
+Layer 3 addresses
+
+- IPv4 and IPv6 addresses, subnets, masks, prefixes
+- iterating, slicing, sorting, summarizing and classifying IP networks
+- dealing with various ranges formats (CIDR, arbitrary ranges and globs, nmap)
+- set based operations (unions, intersections etc) over IP addresses and subnets
+- parsing a large variety of different formats and notations
+- looking up IANA IP block information
+- generating DNS reverse lookups
+- supernetting and subnetting
+
+Layer 2 addresses
+
+- representation and manipulation MAC addresses and EUI-64 identifiers
+- looking up IEEE organisational information (OUI, IAB)
+- generating derived IPv6 addresses
+
+.. toctree::
+    :maxdepth: 1
+
+    reference/compatibility
+    api
+    changes
+    references
+    copyright
+    license
diff --git a/docs/source/reference/compatibility.rst b/docs/source/reference/compatibility.rst
new file mode 100644
index 0000000..64072ab
--- /dev/null
+++ b/docs/source/reference/compatibility.rst
@@ -0,0 +1,39 @@
+Compatibility
+=============
+
+Supported Python versions
+-------------------------
+
+netaddr supports the following Python versions (CPython and PyPy):
+
+* 2.7
+* 3.5
+* 3.6
+* 3.7
+* 3.8
+* 3.9
+* 3.10
+* 3.11
+* 3.12
+
+Support for the following versions is **deprecated and will be removed** (likely
+in netaddr 1.0):
+
+* 2.7
+* 3.5
+* 3.6
+
+Support **deprecated and scheduled to be removed** in netaddr 2:
+
+* 3.7
+
+Supported operating systems
+---------------------------
+
+The library is operating system-independent.
+
+
+Supported hardware architectures
+--------------------------------
+
+The library is hardware architecture-independent.
diff --git a/docs/source/references.rst b/docs/source/references.rst
new file mode 100644
index 0000000..01109cc
--- /dev/null
+++ b/docs/source/references.rst
@@ -0,0 +1,113 @@
+========================
+Standards and References
+========================
+
+The following references are applicable to the netaddr library.
+
+----
+RFCs
+----
+
+The following RFCs have guided netaddr's feature set and capabilities.
+
+^^^^
+IPv4
+^^^^
+
+RFC 791 - Internet Protocol
+    - http://www.ietf.org/rfc/rfc791
+
+RFC 1918 - Address Allocation for Private Internets
+    - http://www.ietf.org/rfc/rfc1918
+
+RFC 3330 - Special-Use IPv4 Addresses
+    - http://www.ietf.org/rfc/rfc3330
+
+RFC 3927 - Dynamic Configuration of IPv4 Link-Local Addresses
+    - http://www.ietf.org/rfc/rfc3927
+
+^^^^^^^^^^^^^^^^
+Multicast (IPv4)
+^^^^^^^^^^^^^^^^
+
+RFC 2365 - Administratively Scoped IP Multicast
+    - http://www.ietf.org/rfc/rfc2365
+
+RFC 3171 - IANA IPv4 Multicast Guidelines
+    - http://www.ietf.org/rfc/rfc3171
+
+RFC 3927 - Dynamic Configuration of IPv4 Link-Local Addresses
+    - http://www.ietf.org/rfc/rfc3927
+
+^^^^
+IPv6
+^^^^
+
+RFC 3330 - Special-Use IPv4 Addresses
+    - http://www.ietf.org/rfc/rfc3330
+
+RFC 4291 - IPv6 Addressing Architecture
+    - http://www.ietf.org/rfc/rfc4291
+
+RFC 3306 - Unicast-Prefix-based IPv6 Multicast
+    - http://www.ietf.org/rfc/rfc3306
+
+RFC 3956 - The RP Address in IPv6 Multicast Address
+    - http://www.ietf.org/rfc/rfc3956
+
+RFC 3879 - Deprecating Site Local Addresses
+    - http://www.ietf.org/rfc/rfc3879
+
+RFC 4193 - Unique Local IPv6 Unicast Addresses
+    - http://www.ietf.org/rfc/rfc4193
+
+RFC 4941 - Privacy Extensions for Stateless Address
+    - http://www.ietf.org/rfc/rfc4941
+
+RFC 1924 - A Compact Representation of IPv6 Addresses
+    - http://www.ietf.org/rfc/rfc1924
+
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Classless Inter-Domain Routing (CIDR)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+RFC 1338 - Supernetting: an Address Assignment and Aggregation Strategy
+    - http://www.ietf.org/rfc/rfc1338
+
+RFC 4632 - Classless Inter-domain Routing (CIDR): The Internet Address Assignment and Aggregation Plan
+    - http://www.ietf.org/rfc/rfc4632
+
+------------
+Data Sources
+------------
+
+Data from the following sources is exposed via the netaddr API.
+
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Internet Assigned Numbers Authority (IANA)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+IANA Protocol Registry
+    - http://www.iana.org/protocols/
+
+IPv4 Address Space
+    - http://www.iana.org/assignments/ipv4-address-space
+
+IPv6 Address Space
+    - http://www.iana.org/assignments/ipv6-address-space
+
+Multicast Registrations
+    - http://www.iana.org/assignments/multicast-addresses
+
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Institute of Electrical and Electronics Engineers (IEEE)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+IEEE Organisation Registry
+    - http://standards.ieee.org/regauth/oui/index.shtml
+
+OUI (Organisationally Unique Identifier) Registrations
+    - http://standards.ieee.org/regauth/oui/oui.txt
+
+IAB (Individual Address Block) Registrations
+    - http://standards.ieee.org/regauth/oui/iab.txt
diff --git a/docs/source/static/custom.css b/docs/source/static/custom.css
new file mode 100644
index 0000000..d023d9a
--- /dev/null
+++ b/docs/source/static/custom.css
@@ -0,0 +1,5 @@
+article a.reference.external::after {
+      content: url('data:image/svg+xml,<svg width="12" height="12" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" stroke-width="1.5" stroke="%23607D8B" fill="none" stroke-linecap="round" stroke-linejoin="round"><path stroke="none" d="M0 0h24v24H0z"/><path d="M11 7h-5a2 2 0 0 0 -2 2v9a2 2 0 0 0 2 2h9a2 2 0 0 0 2 -2v-5" /><line x1="10" y1="14" x2="20" y2="4" /><polyline points="15 4 20 4 20 9" /></svg>');
+      margin: 0 0.1em;
+      vertical-align: middle;
+}
diff --git a/docs/source/tutorial_01.rst b/docs/source/tutorial_01.rst
new file mode 100644
index 0000000..ab6ce40
--- /dev/null
+++ b/docs/source/tutorial_01.rst
@@ -0,0 +1,6 @@
+============================================
+Tutorial 1: IP Addresses, Subnets and Ranges
+============================================
+
+.. include:: ../../tutorials/2.x/ip/tutorial.txt
+
diff --git a/docs/source/tutorial_02.rst b/docs/source/tutorial_02.rst
new file mode 100644
index 0000000..ade6f22
--- /dev/null
+++ b/docs/source/tutorial_02.rst
@@ -0,0 +1,5 @@
+=========================
+Tutorial 2: MAC addresses
+=========================
+
+.. include:: ../../tutorials/2.x/eui/tutorial.txt
diff --git a/docs/source/tutorial_03.rst b/docs/source/tutorial_03.rst
new file mode 100644
index 0000000..e80335b
--- /dev/null
+++ b/docs/source/tutorial_03.rst
@@ -0,0 +1,5 @@
+================================
+Tutorial 3: Working with IP sets
+================================
+
+.. include:: ../../tutorials/2.x/ip/sets.txt
diff --git a/docs/source/tutorials.rst b/docs/source/tutorials.rst
new file mode 100644
index 0000000..b70bd8d
--- /dev/null
+++ b/docs/source/tutorials.rst
@@ -0,0 +1,14 @@
+Tutorials
+=========
+
+The pages in this section take you on a step-by-step journey through some of the
+netaddr's features.
+
+Start here if you're new to netaddr.
+
+.. toctree::
+    :maxdepth: 1
+
+    tutorial_01
+    tutorial_02
+    tutorial_03