From 92ae130c38520b249eb7351cfb0da1ad67d3d3cf Mon Sep 17 00:00:00 2001 From: kotfu 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 `_ 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 `_ package manager can be used to to install the ``readline`` package. - For Windows, we recommend installing the `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 `_, `video `_ +.. 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 From 11da5ba65a43c63364e702de726a7bf09a1241b4 Mon Sep 17 00:00:00 2001 From: kotfu Date: Tue, 2 Jul 2019 19:34:37 -0600 Subject: Skeleton doc structure complete for #709 --- docs/index.rst | 13 +++++++++++++ 1 file changed, 13 insertions(+) (limited to 'docs/index.rst') diff --git a/docs/index.rst b/docs/index.rst index 515209e8..df9a1513 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -70,9 +70,22 @@ Features features/generating_output features/argument_processing + features/prompt features/help + features/history + features/startup_commands + features/shortcuts_aliases_macros + features/settings + features/completion + features/os + features/multiline + features/disable_commands + features/clipboard features/transcript features/hooks + features/plugins + features/scripting + features/embedded_python_shells Examples -- cgit v1.2.1 From 51ea4ba9fbcdfc785a5e9d6bafcac69334e535a8 Mon Sep 17 00:00:00 2001 From: kotfu Date: Wed, 3 Jul 2019 11:23:58 -0600 Subject: Revise menu structure - collapse menu structure in sidebar so not everything is always shown - updates to Getting Started section --- docs/index.rst | 66 +++++++++++++--------------------------------------------- 1 file changed, 14 insertions(+), 52 deletions(-) (limited to 'docs/index.rst') diff --git a/docs/index.rst b/docs/index.rst index df9a1513..68106d9f 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -24,21 +24,16 @@ The basic use of ``cmd2`` is identical to that of cmd_. app.cmdloop() -Overview --------- +Getting Started +--------------- -[create links with short descriptions to the various overview pages here] +.. include:: overview/summary.rst .. toctree:: :maxdepth: 2 :hidden: - :caption: Overview - overview/featuretour - overview/installation - overview/alternatives - overview/resources - examples/quickstart + overview/index Migrating from cmd @@ -48,14 +43,8 @@ Migrating from cmd .. toctree:: :maxdepth: 2 - :hidden: - :caption: Migrating from cmd - migrating/why - migrating/incompatibilities - migrating/minimum - migrating/free_features - migrating/nextsteps + migrating/index Features @@ -65,55 +54,28 @@ Features .. toctree:: :maxdepth: 2 - :hidden: - :caption: Features - - features/generating_output - features/argument_processing - features/prompt - features/help - features/history - features/startup_commands - features/shortcuts_aliases_macros - features/settings - features/completion - features/os - features/multiline - features/disable_commands - features/clipboard - features/transcript - features/hooks - features/plugins - features/scripting - features/embedded_python_shells + features/index -Examples --------------------- -[create links with short descriptions to the various examples pages here] +API Reference +------------- .. toctree:: :maxdepth: 2 - :hidden: - :caption: Examples - examples/quickstart + api/index -API Reference -------------- +Examples +-------------------- + +[create links with short descriptions to the various examples pages here] .. toctree:: :maxdepth: 2 - :hidden: - :caption: API Reference - api/cmd - api/decorators - api/exceptions - api/utility_functions - api/utility_classes + examples/index Meta -- cgit v1.2.1 From 4c97ab03825151fd85a875617fde7d0534c9cb72 Mon Sep 17 00:00:00 2001 From: kotfu Date: Wed, 3 Jul 2019 11:34:35 -0600 Subject: Fix headers --- docs/index.rst | 24 ++++++++++++++++-------- 1 file changed, 16 insertions(+), 8 deletions(-) (limited to 'docs/index.rst') diff --git a/docs/index.rst b/docs/index.rst index 68106d9f..9480dfd4 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -1,3 +1,4 @@ +==== cmd2 ==== @@ -25,19 +26,19 @@ The basic use of ``cmd2`` is identical to that of cmd_. Getting Started ---------------- +=============== .. include:: overview/summary.rst .. toctree:: - :maxdepth: 2 + :maxdepth: 1 :hidden: overview/index Migrating from cmd ------------------- +================== [create links with short descriptions to the various migrating pages here] @@ -48,7 +49,7 @@ Migrating from cmd Features --------- +======== [create links with short descriptions to the various feature pages here] @@ -59,7 +60,7 @@ Features API Reference -------------- +============= .. toctree:: :maxdepth: 2 @@ -68,7 +69,7 @@ API Reference Examples --------------------- +======== [create links with short descriptions to the various examples pages here] @@ -79,7 +80,9 @@ Examples Meta ----- +==== + +:doc:`doc_conventions` .. toctree:: :maxdepth: 2 @@ -90,10 +93,15 @@ Meta 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: -- cgit v1.2.1 From baf2e4665f7766354dea1e2f3b6c881e2c51be1b Mon Sep 17 00:00:00 2001 From: kotfu Date: Sat, 6 Jul 2019 17:32:02 -0600 Subject: Add copyright links per comments in #712 --- docs/index.rst | 1 + 1 file changed, 1 insertion(+) (limited to 'docs/index.rst') diff --git a/docs/index.rst b/docs/index.rst index 9480dfd4..27432132 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -90,6 +90,7 @@ Meta :caption: Meta doc_conventions + copyright To Be Integrated -- cgit v1.2.1