beeware · freakboy3742 · Oct 5, 2017 · Oct 5, 2017
diff --git a/docs/_static/logo.png → docs/_static/images/briefcase.png b/docs/_static/logo.png → docs/_static/images/briefcase.png
diff --git a/docs/intro/community.rst → docs/background/community.rst b/docs/intro/community.rst → docs/background/community.rst
diff --git a/docs/intro/faq.rst → docs/background/faq.rst b/docs/intro/faq.rst → docs/background/faq.rst
diff --git a/docs/intro/getting-started.rst → docs/background/getting-started.rst b/docs/intro/getting-started.rst → docs/background/getting-started.rst
@@ -100,4 +100,4 @@ Next Steps
 ----------
 
 You now have a working Briefcase environment, so you can :doc:`start the first
-tutorial </tutorials/tutorial-0>`.
+tutorial </tutorial/tutorial-0>`.
diff --git a/docs/intro/index.rst → docs/background/index.rst b/docs/intro/index.rst → docs/background/index.rst
@@ -1,3 +1,6 @@
+.. _background:
+
+===============
 About Briefcase
 ===============
 
@@ -8,3 +11,4 @@ About Briefcase
    community
    faq
    getting-started
+   quickstart
diff --git a/docs/intro/quickstart.rst → docs/background/quickstart.rst b/docs/intro/quickstart.rst → docs/background/quickstart.rst
diff --git a/docs/conf.py b/docs/conf.py
@@ -11,11 +11,11 @@
 # 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.
+import sys
+import os
 #sys.path.insert(0, os.path.abspath('.'))
 
 # -- General configuration -----------------------------------------------------
@@ -47,6 +47,15 @@
 # |version| and |release|, also used in various other places throughout the
 # built documents.
 #
+# The full version, including alpha/beta/rc tags.
+import io, re
+with io.open('../briefcase/__init__.py', encoding='utf8') as version_file:
+    version_match = re.search(r"^__version__ = ['\"]([^'\"]*)['\"]", version_file.read(), re.M)
+    if version_match:
+        release = version_match.group(1)
+    else:
+        raise RuntimeError("Unable to find version string.")
+
 # The short X.Y version.
 version = '0.1'
 # The full version, including alpha/beta/rc tags.
@@ -89,9 +98,17 @@
 
 # -- 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 = 'default'
+# on_rtd: whether we are on readthedocs.org
+on_rtd = os.environ.get('READTHEDOCS', None) == 'True'
+
+if not on_rtd:  # only import and set the theme if we're building docs locally
+    try:
+        import sphinx_rtd_theme
+    except ModuleNotFoundError:
+        html_theme = 'default'
+    else:
+        html_theme = 'sphinx_rtd_theme'
+        html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
 
 # 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
@@ -110,7 +127,7 @@
 
 # The name of an image file (relative to this directory) to place at the top
 # of the sidebar.
-#html_logo = None
+html_logo = "_static/images/briefcase.png"
 
 # 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
@@ -166,6 +183,13 @@
 # Output file base name for HTML help builder.
 htmlhelp_basename = 'briefcasedoc'
 
+try:
+    import sphinx_rtd_theme
+    html_theme = "sphinx_rtd_theme"
+    html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
+except ImportError:
+    # The sphinx-rtd-theme package is not installed, so to the default
+    pass
 
 # -- Options for LaTeX output --------------------------------------------------
 
@@ -240,3 +264,18 @@
 
 # How to display URL addresses: 'footnote', 'no', or 'inline'.
 #texinfo_show_urls = 'footnote'
+
+# -- Options for spelling -------------------------------------------
+
+# Spelling check needs an additional module that is not installed by default.
+# Add it only if spelling check is requested so docs can be generated without it.
+if 'spelling' in sys.argv:
+    extensions.append("sphinxcontrib.spelling")
+
+# Spelling language.
+spelling_lang = 'en_US'
+
+# Location of word list.
+spelling_word_list_filename = 'spelling_wordlist'
+
+spelling_ignore_pypi_package_names = True
diff --git a/docs/internals/contributing.rst → docs/how-to/contribute.rst b/docs/internals/contributing.rst → docs/how-to/contribute.rst
diff --git a/docs/howto/index.rst → docs/how-to/index.rst b/docs/howto/index.rst → docs/how-to/index.rst
@@ -1,3 +1,6 @@
+.. _how-to:
+
+=============
 How-to guides
 =============
 
@@ -7,3 +10,4 @@ How-to guides are recipes that take the user through steps in key subjects. They
    :maxdepth: 1
    :glob:
 
+   Contribute to Briefcase <contribute>
diff --git a/docs/index.rst b/docs/index.rst
@@ -1,9 +1,34 @@
+.. raw:: html
+
+    <style>
+        .row {clear: both}
+
+        .column img {border: 1px solid black;}
+
+        @media only screen and (min-width: 1000px),
+               only screen and (min-width: 500px) and (max-width: 768px){
+
+            .column {
+                padding-left: 5px;
+                padding-right: 5px;
+                float: left;
+            }
+
+            .column3  {
+                width: 33.3%;
+            }
+
+            .column2  {
+                width: 50%;
+            }
+        }
+    </style>
+
+
+=========
 Briefcase
 =========
 
-.. image:: _static/logo.png
-    :target: https://pybee.org/briefcase
-
 Briefcase is a tool for converting a Python project into a standalone
 native application. It supports producing binaries for:
 
@@ -16,13 +41,69 @@ native application. It supports producing binaries for:
 * tvOS.
 
 
+.. rst-class::  row
+
+Table of contents
+=================
+
+.. rst-class:: clearfix row
+
+.. rst-class:: column column2
+
+:ref:`Tutorial <tutorial>`
+--------------------------
+
+Get started with a hands-on introduction for beginners
+
+
+.. rst-class:: column column2
+
+:ref:`How-to guides <how-to>`
+-----------------------------
+
+Guides and recipes for common problems and tasks, including how to contribute
+
+
+.. rst-class:: column column2
+
+:ref:`Background <background>`
+------------------------------
+
+Explanation and discussion of key topics and concepts
+
+
+.. rst-class:: column column2
+
+:ref:`Reference <reference>`
+----------------------------
+
+Technical reference - commands, modules, classes, methods
+
+
+.. rst-class:: clearfix row
+
+Community
+=========
+
+Rubicon is part of the `BeeWare suite`_. You can talk to the community through:
+
+ * `@pybeeware on Twitter`_
+
+ * `pybee/general on Gitter`_
+
+.. _BeeWare suite: http://pybee.org
+.. _Read The Docs: https://briefcase.readthedocs.io
+.. _@pybeeware on Twitter: https://twitter.com/pybeeware
+.. _pybee/general on Gitter: https://gitter.im/pybee/general
+
+
 .. toctree::
    :maxdepth: 2
-   :glob:
+   :hidden:
+   :titlesonly:
 
-   intro/index
-   tutorials/index
-   howto/index
-   topics/index
+   tutorial/index
+   how-to/index
    reference/index
-   internals/index
+   background/index
+   project/index
diff --git a/docs/internals/index.rst → docs/project/index.rst b/docs/internals/index.rst → docs/project/index.rst
@@ -1,10 +1,12 @@
-Project Internals
+.. _project:
+
+=================
+About the project
 =================
 
 .. toctree::
-   :maxdepth: 1
+   :maxdepth: 2
    :glob:
 
-   contributing
    releases
    roadmap
diff --git a/docs/internals/releases.rst → docs/project/releases.rst b/docs/internals/releases.rst → docs/project/releases.rst
diff --git a/docs/internals/roadmap.rst → docs/project/roadmap.rst b/docs/internals/roadmap.rst → docs/project/roadmap.rst
diff --git a/docs/reference/index.rst b/docs/reference/index.rst
@@ -1,4 +1,10 @@
+.. _reference:
+
+=========
 Reference
 =========
 
+.. toctree::
+   :maxdepth: 1
+
 This is the technical reference for public APIs provided by Briefcase.
diff --git a/docs/requirements_docs.txt b/docs/requirements_docs.txt
@@ -0,0 +1,5 @@
+sphinx
+sphinxcontrib-spelling
+pyenchant
+sphinx-autobuild
+sphinx_rtd_theme
diff --git a/docs/spelling_wordlist b/docs/spelling_wordlist
diff --git a/docs/topics/index.rst b/docs/topics/index.rst
diff --git a/docs/tutorials/index.rst → docs/tutorial/index.rst b/docs/tutorials/index.rst → docs/tutorial/index.rst
@@ -1,11 +1,14 @@
+.. _tutorial:
+
+=========
 Tutorials
 =========
 
 These tutorials are step-by step guides for using Briefcase.
 
 .. toctree::
-   :maxdepth: 2
-   :glob:
+   :maxdepth: 1
+   :titlesonly:
 
    tutorial-0
    tutorial-1
diff --git a/...torials/screenshots/tutorial-1-django.png → ...utorial/screenshots/tutorial-1-django.png b/...torials/screenshots/tutorial-1-django.png → ...utorial/screenshots/tutorial-1-django.png
diff --git a/.../tutorials/screenshots/tutorial-1-ios.png → docs/tutorial/screenshots/tutorial-1-ios.png b/.../tutorials/screenshots/tutorial-1-ios.png → docs/tutorial/screenshots/tutorial-1-ios.png
diff --git a/docs/tutorials/tutorial-0.rst → docs/tutorial/tutorial-0.rst b/docs/tutorials/tutorial-0.rst → docs/tutorial/tutorial-0.rst
@@ -8,7 +8,7 @@ Setup
 -----
 
 This tutorial assumes you've read and followed the instructions in
-:doc:`/intro/getting-started`. If you've done this, you should have:
+:doc:`/background/getting-started`. If you've done this, you should have:
 
 * A ``tutorial`` directory,
 * A activated Python 3.5 virtual environment,
@@ -140,4 +140,4 @@ application, with a native icon in your task bar (or wherever icons appear on
 your platform).
 
 You've just packaged your first app with Briefcase! Now, let's :doc:`make the
-app actually do something interesting </tutorials/tutorial-1>`.
+app actually do something interesting </tutorial/tutorial-1>`.
diff --git a/docs/tutorials/tutorial-1.rst → docs/tutorial/tutorial-1.rst b/docs/tutorials/tutorial-1.rst → docs/tutorial/tutorial-1.rst
@@ -91,7 +91,7 @@ Use the *same code*, but for the web
 
 Now, we're going to deploy the same code, but as a single page web
 application. Make sure you have the Django dependencies installed (see
-:doc:`/intro/getting-started`), and run the following:
+:doc:`/background/getting-started`), and run the following:
 
 .. code-block:: bash