Merge pull request #712 from python-cmd2/docstructure

New Documentation Structure

1 files changed, 78 insertions, 45 deletions

diff --git a/docs/index.rst b/docs/index.rst
index 5f9c4c3d..27432132 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -1,23 +1,16 @@
-.. 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 +24,91 @@ 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.
+Getting Started
+===============
 
-Resources
----------
+.. include:: overview/summary.rst
+
+.. toctree::
+   :maxdepth: 1
+   :hidden:
+
+   overview/index
 
-* 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>`_
 
-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.
+Migrating from cmd
+==================
 
-Contents:
+[create links with short descriptions to the various migrating pages here]
 
 .. toctree::
    :maxdepth: 2
 
-   install
-   overview
-   freefeatures
-   settingchanges
-   unfreefeatures
-   transcript
-   argument_processing
-   integrating
-   hooks
-   alternatives
+   migrating/index
+
+
+Features
+========
+
+[create links with short descriptions to the various feature pages here]
+
+.. toctree::
+   :maxdepth: 2
+
+   features/index
+
 
-Compatibility
+API Reference
 =============
 
-Tested and working with Python 3.5+ on Windows, macOS, and Linux.
+.. toctree::
+   :maxdepth: 2
+
+   api/index
 
-Index
-=====
 
-* :ref:`genindex`
+Examples
+========
+
+[create links with short descriptions to the various examples pages here]
+
+.. toctree::
+   :maxdepth: 2
+
+   examples/index
+
+
+Meta
+====
+
+:doc:`doc_conventions`
+
+.. toctree::
+   :maxdepth: 2
+   :hidden:
+   :caption: Meta
+
+   doc_conventions
+   copyright
+
+
+To Be Integrated
+================
+
+Files from old documentation to be integrated into new structure
+
+* :doc:`freefeatures`
+* :doc:`integrating`
+* :doc:`settingchanges`
+* :doc:`unfreefeatures`
+
+.. toctree::
+   :maxdepth: 2
+   :hidden:
+   :caption: To Be Integrated
+
+   freefeatures
+   integrating
+   settingchanges
+   unfreefeatures