Merge branch 'new-docs' into develop

README.md

@@ -15,62 +15,14 @@ Questions? Comments? Please join us on IRC in **#netbox** on **irc.freenode.net*
 
 ## Screenshots
 
-![Screenshot of main page](docs/screenshot1.png "Main page")
+![Screenshot of main page](docs/media/screenshot1.png "Main page")
 
-![Screenshot of rack elevation](docs/screenshot2.png "Rack elevation")
+![Screenshot of rack elevation](docs/media/screenshot2.png "Rack elevation")
 
-![Screenshot of prefix hierarchy](docs/screenshot3.png "Prefix hierarchy")
+![Screenshot of prefix hierarchy](docs/media/screenshot3.png "Prefix hierarchy")
 
 # Installation
 
 Please see docs/getting-started.md for instructions on installing NetBox.
 
 To upgrade NetBox, please download the [latest release](https://github.com/digitalocean/netbox/releases) and run `upgrade.sh`.
-
-# Components
-
-NetBox understands all of the physical and logical building blocks that comprise network infrastructure, and the manners in which they are all related.
-
-## DCIM
-
-DCIM comprises all the physical installations and connections which comprise a network. NetBox tracks where devices are installed, as well as their individual power, console, and network connections.
-
-**Site:** A physical location (typically a building) where network devices are installed. Devices in different sites cannot be directly connected to one another.
-
-**Rack:** An equipment rack into which devices are installed. Each rack belongs to a site.
-
-**Device:** Any type of rack-mounted device. For example, routers, switches, servers, console servers, PDUs, etc. 0U (non-rack-mounted) devices are supported.
-
-## IPAM
-
-IPAM deals with the IP addressing and VLANs in use on a network. NetBox makes a distinction between IP prefixes (networks) and individual IP addresses.
-
-Because NetBox is a combined DCIM/IPAM system, IP addresses can be assigned to device interfaces in the application just as they are in the real world.
-
-**Aggregate:** A top-level aggregate of IP address space; for example, 10.0.0.0/8 or 2001:db8::/32. Each aggregate belongs to a regional Internet registry (RIR) like ARIN or RIPE, or to an authoritative standard such as RFC 1918.
-
-**VRF:** A virtual routing table. VRF support is currently still under development.
-
-**Prefix:** An IPv4 or IPv6 network. A prefix can be assigned to a VRF; if not, it is considered to belong to the global table. Prefixes are grouped by aggregates automatically and can optionally be assigned to sites.
-
-**IP Address:** An individual IPv4 or IPv6 address (with CIDR mask). IP address can be assigned to device interfaces.
-
-**VLAN:** VLANs are assigned to sites, and can optionally have one or more IP prefixes assigned to them. VLAN IDs are unique only within the scope of a site.
-
-## Circuits
-
-Long-distance data connections are typically referred to as _circuits_. NetBox provides a method for managing circuits and their providers. Individual circuits can be terminated to device interfaces.
-
-**Provider:** An entity to which a network connects to. This can be a transit provider, peer, or some other organization.
-
-**Circuit:** A data circuit which connects to a provider. The local end of a circuit can be assigned to a device interface.
-
-## Secrets
-
-NetBox provides encrypted storage of sensitive data it calls _secrets_. Each user may be issued an encryption key with which stored secrets can be retrieved.
-
-Note that NetBox does not merely hash secrets, a function which is only useful for validation. It employs fully reversible AES-256 encryption so that secret data can be retrieved and consumed by other services.
-
-**Secrets** Any piece of confidential data which must be retrievable. For example: passwords, SNMP communities, RADIUS shared secrets, etc.
-
-**User Key:** An individual user's encrypted copy of the master key, which can be used to retrieve secret data.

docs/getting-started.md

@@ -1,5 +1,3 @@
-<h1>Getting Started</h1>
-
 This guide documents the process of installing NetBox on an Ubuntu 14.04 server with [nginx](https://www.nginx.com/) and [gunicorn](http://gunicorn.org/).
 
 [TOC]

docs/index.md

@@ -1,3 +1,39 @@
-# NetBox Documentation
+# What is NetBox?
 
-NetBox is an IP address management (IPAM) and data center infrastructure management (DCIM) application.
+NetBox is an open source web application designed to help manage and document computer networks. Initially conceived by the network engineering team at [DigitalOcean](https://www.digitalocean.com/), NetBox was developed specifically to address the needs of network and infrastructure engineers. It encompasses the following aspects of network management:
+
+* **IP address management (IPAM)** - IP networks and addresses, VRFs, and VLANs
+* **Equipment racks** - Organized by group and site
+* **Devices** - Types of devices and where they are installed
+* **Connections** - Network, console, and power connections among devices
+* **Data circuits** - Long-haul communications circuits and providers
+* **Secrets** - Encrypted storage of sensitive credentials
+
+It was designed with the following tenets foremost in mind.
+
+### Replicate the Real World
+
+Careful consideration has been given to the data model to ensure that it can accurately reflect a real-world network. For instance, IP addresses are assigned not to devices, but to specific interfaces attached to a device, and an interface may have multiple IP addresses assigned to it.
+
+### Serve as a "Source of Truth"
+
+NetBox intends to represent the _desired_ state of a network versus its _operational_ state. As such, automated import of live network state is strongly discouraged. All data created in NetBox should first be vetted by a human to ensure its integrity. NetBox can then be used to populate monitoring and provisioning systems with a high degree of confidence.
+
+### Keep it Simple
+
+When given a choice between a relatively simple [80% solution](https://en.wikipedia.org/wiki/Pareto_principle) and a much more complex complete solution, the former will typically be favored. This ensures a lean codebase with a low learning curve.
+
+# Application Stack
+
+NetBox is built on the [Django](https://djangoproject.com/) Python framework and utilizes a [PostgreSQL](https://www.postgresql.org/) database. It runs as a WSGI service behind your choice of HTTP server.
+
+| Function     | Component         |
+|--------------|-------------------|
+| HTTP Service | nginx or Apache   |
+| WSGI Service | gunicorn or uWSGI |
+| Application  | Django/Python     |
+| Database     | PostgreSQL        |
+
+# Getting Started
+
+See the [getting started](getting-started.md) guide for help with getting NetBox up and running quickly.

netbox/netbox/urls.py

@@ -2,7 +2,7 @@ from django.conf.urls import include, url
 from django.contrib import admin
 from django.views.defaults import page_not_found
 
-from views import home, docs, trigger_500
+from views import home, trigger_500
 from users.views import login, logout
 
 
@@ -30,10 +30,6 @@ urlpatterns = [
     url(r'^api/docs/', include('rest_framework_swagger.urls')),
     url(r'^api-auth/', include('rest_framework.urls', namespace='rest_framework')),
 
-    # Dcoumentation
-    url(r'^docs/$', docs, kwargs={'path': 'index'}, name='docs_root'),
-    url(r'^docs/(?P<path>[\w-]+)/$', docs, name='docs'),
-
     # Error testing
     url(r'^404/$', page_not_found),
     url(r'^500/$', trigger_500),

netbox/netbox/views.py

@@ -45,25 +45,6 @@ def home(request):
     })
 
 
-def docs(request, path):
-    """
-    Display a page of Markdown-formatted documentation.
-    """
-    filename = '{}/docs/{}.md'.format(settings.BASE_DIR.rsplit('/', 1)[0], path)
-    try:
-        with open(filename, 'r') as docfile:
-            markup = docfile.read()
-    except:
-        raise Http404
-
-    content = mark_safe(markdown(markup, extensions=['mdx_gfm', 'toc']))
-
-    return render(request, 'docs.html', {
-        'content': content,
-        'path': path,
-    })
-
-
 def trigger_500(request):
     """Hot-wired method of triggering a server error to test reporting."""
 

netbox/templates/_base.html

@@ -252,7 +252,7 @@
                 </div>
                 <div class="col-md-4 text-right">
                     <p class="text-muted">
-                        <i class="fa fa-fw fa-book text-primary"></i> <a href="{% url 'docs_root' %}">Docs</a> &middot;
+                        <i class="fa fa-fw fa-book text-primary"></i> <a href="http://netbox.readthedocs.io/" target="_blank">Docs</a> &middot;
                         <i class="fa fa-fw fa-cloud text-primary"></i> <a href="/api/docs/">API</a> &middot;
                         <i class="fa fa-fw fa-code text-primary"></i> <a href="https://github.com/digitalocean/netbox">Code</a>
                     </p>