From 92ae130c38520b249eb7351cfb0da1ad67d3d3cf Mon Sep 17 00:00:00 2001
From: kotfu <kotfu@kotfu.net>
Date: Tue, 2 Jul 2019 19:02:36 -0600
Subject: Major overhaul of documentation structure for #709

---
 docs/index.rst | 141 ++++++++++++++++++++++++++++++++++++++-------------------
 1 file changed, 95 insertions(+), 46 deletions(-)

(limited to 'docs/index.rst')

diff --git a/docs/index.rst b/docs/index.rst
index 5f9c4c3d..515209e8 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -1,23 +1,15 @@
-.. cmd2 documentation master file, created by
-   sphinx-quickstart on Wed Feb 10 12:05:28 2010.
-   You can adapt this file completely to your liking, but it should at least
-   contain the root `toctree` directive.
-
 cmd2
 ====
 
-A python package for building powerful command-line interpreter (CLI)
-programs.  Extends the Python Standard Library's cmd_ package.
+.. default-domain:: py
 
 .. _cmd: https://docs.python.org/3/library/cmd.html
-.. _`cmd2 project page`: https://github.com/python-cmd2/cmd2
-.. _`project bug tracker`: https://github.com/python-cmd2/cmd2/issues
 
+A python package for building powerful command-line interpreter (CLI)
+programs.  Extends the Python Standard Library's cmd_ package.
 
 The basic use of ``cmd2`` is identical to that of cmd_.
 
-.. highlight:: python
-
 1. Create a subclass of ``cmd2.Cmd``.  Define attributes and
    ``do_*`` methods to control its behavior.  Throughout this documentation,
    we will assume that you are naming your subclass ``App``::
@@ -31,51 +23,108 @@ The basic use of ``cmd2`` is identical to that of cmd_.
      app = App()
      app.cmdloop()
 
-.. note::
 
-   The tab-completion feature provided by cmd_ relies on underlying capability provided by GNU readline or an
-   equivalent library.  Linux distros will almost always come with the required library installed.
-   For macOS, we recommend using the `gnureadline <https://pypi.python.org/pypi/gnureadline>`_ Python module which includes
-   a statically linked version of GNU readline.  Alternatively on macOS the ``conda`` package manager that comes
-   with the Anaconda Python distro can be used to install ``readline`` (preferably from conda-forge) or the
-   `Homebrew <https://brew.sh>`_ package manager can be used to to install the ``readline`` package.
-   For Windows, we recommend installing the `pyreadline <https://pypi.python.org/pypi/pyreadline>`_ Python module.
+Overview
+--------
 
-Resources
----------
+[create links with short descriptions to the various overview pages here]
 
-* cmd_
-* `cmd2 project page`_
-* `project bug tracker`_
-* Florida PyCon 2017: `slides <https://docs.google.com/presentation/d/1LRmpfBt3V-pYQfgQHdczf16F3hcXmhK83tl77R6IJtE>`_, `video <https://www.youtube.com/watch?v=6m0RdpITaeY>`_
+.. toctree::
+   :maxdepth: 2
+   :hidden:
+   :caption: Overview
+
+   overview/featuretour
+   overview/installation
+   overview/alternatives
+   overview/resources
+   examples/quickstart
 
-These docs will refer to ``App`` as your ``cmd2.Cmd``
-subclass, and ``app`` as an instance of ``App``.  Of
-course, in your program, you may name them whatever
-you want.
 
-Contents:
+Migrating from cmd
+------------------
+
+[create links with short descriptions to the various migrating pages here]
 
 .. toctree::
    :maxdepth: 2
+   :hidden:
+   :caption: Migrating from cmd
 
-   install
-   overview
-   freefeatures
-   settingchanges
-   unfreefeatures
-   transcript
-   argument_processing
-   integrating
-   hooks
-   alternatives
+   migrating/why
+   migrating/incompatibilities
+   migrating/minimum
+   migrating/free_features
+   migrating/nextsteps
+
+
+Features
+--------
+
+[create links with short descriptions to the various feature pages here]
+
+.. toctree::
+   :maxdepth: 2
+   :hidden:
+   :caption: Features
+
+   features/generating_output
+   features/argument_processing
+   features/help
+   features/transcript
+   features/hooks
 
-Compatibility
-=============
 
-Tested and working with Python 3.5+ on Windows, macOS, and Linux.
+Examples
+--------------------
 
-Index
-=====
+[create links with short descriptions to the various examples pages here]
+
+.. toctree::
+   :maxdepth: 2
+   :hidden:
+   :caption: Examples
 
-* :ref:`genindex`
+   examples/quickstart
+
+
+API Reference
+-------------
+
+.. toctree::
+   :maxdepth: 2
+   :hidden:
+   :caption: API Reference
+
+   api/cmd
+   api/decorators
+   api/exceptions
+   api/utility_functions
+   api/utility_classes
+
+
+Meta
+----
+
+.. toctree::
+   :maxdepth: 2
+   :hidden:
+   :caption: Meta
+
+   doc_conventions
+
+
+To Be Integrated
+----------------
+
+Files from old documentation to be integrated into new structure
+
+.. toctree::
+   :maxdepth: 2
+   :hidden:
+   :caption: To Be Integrated
+
+   freefeatures
+   integrating
+   settingchanges
+   unfreefeatures
-- 
cgit v1.2.1