Documentation outline

docs/docs-requirements.txt

@@ -0,0 +1,2 @@
+sphinx
+sphinx_rtd_theme

docs/source/conf.py

@@ -14,7 +14,10 @@
 # serve to show the default.
 
 import sys
+
+# on_rtd is whether we are on readthedocs.org
 import os
+on_rtd = os.environ.get('READTHEDOCS', None) == 'True'
 
 # 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
@@ -103,7 +106,13 @@ pygments_style = 'sphinx'
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
-html_theme = 'default'
+
+if not on_rtd:  # only import and set the theme if we're building docs locally
+    import sphinx_rtd_theme
+    html_theme = 'sphinx_rtd_theme'
+    html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
+
+# otherwise, readthedocs.org uses their theme by default, so no need to specify it
 
 # 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

docs/source/index.rst

@@ -3,14 +3,41 @@
    You can adapt this file completely to your liking, but it should at least
    contain the root `toctree` directive.
 
-Welcome to Segpy's documentation!
-=================================
+=====
+Segpy
+=====
 
-Contents:
+*Segpy* is a Python package for reading and writing SEG Y data. The SEG Y file format is one of several standards
+developed by the Society of Exploration Geophysicists for storing geophysical seismic data. It is an open standard, and
+is controlled by the SEG Technical Standards Committee, a non-profit organization.
+
+This project aims to implement an open SEG Y module in Python for transporting seismic data between SEG Y files and
+Python data structures.
+
+Contents
+========
+
+Front Matter
+------------
 
 .. toctree::
    :maxdepth: 2
 
+Narrative Documentation
+-----------------------
+
+Read this to learn how to use *Segpy*:
+
+
+Reference Documentation
+-----------------------
+
+Descriptions and examples for every public function, class and method in *Segpy*.
+
+
+Change History
+--------------
+
 
 
 Indices and tables