diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/Makefile | 153 | ||||
| -rw-r--r-- | docs/requirements.txt | 2 | ||||
| -rw-r--r-- | docs/source/classes.rst | 63 | ||||
| -rw-r--r-- | docs/source/complete.rst | 45 | ||||
| -rw-r--r-- | docs/source/conf.py | 251 | ||||
| -rw-r--r-- | docs/source/demoapp.rst | 258 | ||||
| -rw-r--r-- | docs/source/developers.rst | 83 | ||||
| -rw-r--r-- | docs/source/history.rst | 163 | ||||
| -rw-r--r-- | docs/source/index.rst | 33 | ||||
| -rw-r--r-- | docs/source/install.rst | 51 | ||||
| -rw-r--r-- | docs/source/interactive_mode.rst | 94 | ||||
| -rw-r--r-- | docs/source/introduction.rst | 64 | ||||
| -rw-r--r-- | docs/source/list_commands.rst | 83 | ||||
| -rw-r--r-- | docs/source/show_commands.rst | 89 |
14 files changed, 0 insertions, 1432 deletions
diff --git a/docs/Makefile b/docs/Makefile deleted file mode 100644 index 0127250..0000000 --- a/docs/Makefile +++ /dev/null @@ -1,153 +0,0 @@ -# Makefile for Sphinx documentation -# - -# You can set these variables from the command line. -SPHINXOPTS = -SPHINXBUILD = sphinx-build -PAPER = -BUILDDIR = build - -# Internal variables. -PAPEROPT_a4 = -D latex_paper_size=a4 -PAPEROPT_letter = -D latex_paper_size=letter -ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source -# the i18n builder cannot share the environment and doctrees with the others -I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source - -.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext - -help: - @echo "Please use \`make <target>' where <target> is one of" - @echo " html to make standalone HTML files" - @echo " dirhtml to make HTML files named index.html in directories" - @echo " singlehtml to make a single large HTML file" - @echo " pickle to make pickle files" - @echo " json to make JSON files" - @echo " htmlhelp to make HTML files and a HTML help project" - @echo " qthelp to make HTML files and a qthelp project" - @echo " devhelp to make HTML files and a Devhelp project" - @echo " epub to make an epub" - @echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter" - @echo " latexpdf to make LaTeX files and run them through pdflatex" - @echo " text to make text files" - @echo " man to make manual pages" - @echo " texinfo to make Texinfo files" - @echo " info to make Texinfo files and run them through makeinfo" - @echo " gettext to make PO message catalogs" - @echo " changes to make an overview of all changed/added/deprecated items" - @echo " linkcheck to check all external links for integrity" - @echo " doctest to run all doctests embedded in the documentation (if enabled)" - -clean: - -rm -rf $(BUILDDIR)/* - -html: - $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html - @echo - @echo "Build finished. The HTML pages are in $(BUILDDIR)/html." - -dirhtml: - $(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml - @echo - @echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml." - -singlehtml: - $(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml - @echo - @echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml." - -pickle: - $(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle - @echo - @echo "Build finished; now you can process the pickle files." - -json: - $(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json - @echo - @echo "Build finished; now you can process the JSON files." - -htmlhelp: - $(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp - @echo - @echo "Build finished; now you can run HTML Help Workshop with the" \ - ".hhp project file in $(BUILDDIR)/htmlhelp." - -qthelp: - $(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp - @echo - @echo "Build finished; now you can run "qcollectiongenerator" with the" \ - ".qhcp project file in $(BUILDDIR)/qthelp, like this:" - @echo "# qcollectiongenerator $(BUILDDIR)/qthelp/cliff.qhcp" - @echo "To view the help file:" - @echo "# assistant -collectionFile $(BUILDDIR)/qthelp/cliff.qhc" - -devhelp: - $(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp - @echo - @echo "Build finished." - @echo "To view the help file:" - @echo "# mkdir -p $$HOME/.local/share/devhelp/cliff" - @echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/cliff" - @echo "# devhelp" - -epub: - $(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub - @echo - @echo "Build finished. The epub file is in $(BUILDDIR)/epub." - -latex: - $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex - @echo - @echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex." - @echo "Run \`make' in that directory to run these through (pdf)latex" \ - "(use \`make latexpdf' here to do that automatically)." - -latexpdf: - $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex - @echo "Running LaTeX files through pdflatex..." - $(MAKE) -C $(BUILDDIR)/latex all-pdf - @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex." - -text: - $(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text - @echo - @echo "Build finished. The text files are in $(BUILDDIR)/text." - -man: - $(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man - @echo - @echo "Build finished. The manual pages are in $(BUILDDIR)/man." - -texinfo: - $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo - @echo - @echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo." - @echo "Run \`make' in that directory to run these through makeinfo" \ - "(use \`make info' here to do that automatically)." - -info: - $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo - @echo "Running Texinfo files through makeinfo..." - make -C $(BUILDDIR)/texinfo info - @echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo." - -gettext: - $(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale - @echo - @echo "Build finished. The message catalogs are in $(BUILDDIR)/locale." - -changes: - $(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes - @echo - @echo "The overview file is in $(BUILDDIR)/changes." - -linkcheck: - $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck - @echo - @echo "Link check complete; look for any errors in the above output " \ - "or in $(BUILDDIR)/linkcheck/output.txt." - -doctest: - $(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest - @echo "Testing of doctests in the sources finished, look at the " \ - "results in $(BUILDDIR)/doctest/output.txt." diff --git a/docs/requirements.txt b/docs/requirements.txt deleted file mode 100644 index 6f01983..0000000 --- a/docs/requirements.txt +++ /dev/null @@ -1,2 +0,0 @@ -httplib2==0.7.4 -prettytable==0.5 diff --git a/docs/source/classes.rst b/docs/source/classes.rst deleted file mode 100644 index 14e80e9..0000000 --- a/docs/source/classes.rst +++ /dev/null @@ -1,63 +0,0 @@ -=============== - Cliff Classes -=============== - -Application -=========== - -App ---- - -.. autoclass:: cliff.app.App - :members: - -InteractiveApp --------------- - -.. autoclass:: cliff.interactive.InteractiveApp - :members: - -CommandManager --------------- - -.. autoclass:: cliff.commandmanager.CommandManager - :members: - -Command -------- - -.. autoclass:: cliff.command.Command - :members: - -ShowOne -------- - -.. autoclass:: cliff.show.ShowOne - :members: - -Lister ------- - -.. autoclass:: cliff.lister.Lister - :members: - -Formatting Output -================= - -Formatter ---------- - -.. autoclass:: cliff.formatters.base.Formatter - :members: - -ListFormatter -------------- - -.. autoclass:: cliff.formatters.base.ListFormatter - :members: - -SingleFormatter ---------------- - -.. autoclass:: cliff.formatters.base.SingleFormatter - :members: diff --git a/docs/source/complete.rst b/docs/source/complete.rst deleted file mode 100644 index 2a08098..0000000 --- a/docs/source/complete.rst +++ /dev/null @@ -1,45 +0,0 @@ -==================== - Command Completion -==================== - -A generic command completion command is available to generate a -bash-completion script. Currently, the command will generate a script -for bash versions 3 or 4. There is also a mode that generates only -data that can be used in your own script. The command completion script -is generated based on the commands and options that you have specified -in cliff. - -Usage -===== - -In order for your command to support command completions, you need to -add the `cliff.complete.CompleteCommand` class to your command manager. - -:: - - self.command_manager.add_command('complete', cliff.complete.CompleteCommand) - -When you run the command, it will generate a bash-completion script: - -:: - - (.venv)$ mycmd complete - _mycmd() - { - local cur prev words - COMPREPLY=() - _get_comp_words_by_ref -n : cur prev words - - # Command data: - cmds='agent aggregate backup' - cmds_agent='--name' - ... - if [ -z "${completed}" ] ; then - COMPREPLY=( $( compgen -f -- "$cur" ) $( compgen -d -- "$cur" ) ) - else - COMPREPLY=( $(compgen -W "${completed}" -- ${cur}) ) - fi - return 0 - } - complete -F _mycmd mycmd - diff --git a/docs/source/conf.py b/docs/source/conf.py deleted file mode 100644 index 131a9f9..0000000 --- a/docs/source/conf.py +++ /dev/null @@ -1,251 +0,0 @@ -# -*- coding: utf-8 -*- -# -# cliff documentation build configuration file, created by -# sphinx-quickstart on Wed Apr 25 11:14:29 2012. -# -# This file is execfile()d with the current directory set to its -# containing dir. -# -# Note that not all possible configuration values are present in this -# autogenerated file. -# -# All configuration values have a default; values that are commented out -# serve to show the default. - -import datetime -import subprocess - -# 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. -#sys.path.insert(0, os.path.abspath('.')) - -# -- General configuration --------------------------------------------------- - -# If your documentation needs a minimal Sphinx version, state it here. -#needs_sphinx = '1.0' - -# Add any Sphinx extension module names here, as strings. They can be -# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom -# ones. -extensions = ['sphinx.ext.autodoc', 'sphinx.ext.todo'] - -# Add any paths that contain templates here, relative to this directory. -templates_path = ['_templates'] - -# The suffix of source filenames. -source_suffix = '.rst' - -# The encoding of source files. -#source_encoding = 'utf-8-sig' - -# The master toctree document. -master_doc = 'index' - -# General information about the project. -project = u'cliff' -copyright = u'2012-%s, Doug Hellmann' % datetime.datetime.today().year - -# The version info for the project you're documenting, acts as replacement for -# |version| and |release|, also used in various other places throughout the -# built documents. -# -# The short X.Y version. -version = subprocess.check_output([ - 'sh', '-c', - 'cd ../..; python setup.py --version', -]) -version = version.strip() -# The full version, including alpha/beta/rc tags. -release = version - -# The language for content autogenerated by Sphinx. Refer to documentation -# for a list of supported languages. -#language = None - -# There are two options for replacing |today|: either, you set today to some -# non-false value, then it is used: -#today = '' -# Else, today_fmt is used as the format for a strftime call. -#today_fmt = '%B %d, %Y' - -# List of patterns, relative to source directory, that match files and -# directories to ignore when looking for source files. -exclude_patterns = [] - -# The reST default role (used for this markup: `text`) to use for all -# documents. -#default_role = None - -# If true, '()' will be appended to :func: etc. cross-reference text. -#add_function_parentheses = True - -# If true, the current module name will be prepended to all description -# unit titles (such as .. function::). -#add_module_names = True - -# If true, sectionauthor and moduleauthor directives will be shown in the -# output. They are ignored by default. -#show_authors = False - -# The name of the Pygments (syntax highlighting) style to use. -pygments_style = 'sphinx' - -# A list of ignored prefixes for module index sorting. -#modindex_common_prefix = [] - - -# -- 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' - -# 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 -# documentation. -#html_theme_options = {} - -# Add any paths that contain custom themes here, relative to this directory. -#html_theme_path = [] - -# The name for this set of Sphinx documents. If None, it defaults to -# "<project> v<release> documentation". -#html_title = None - -# A shorter title for the navigation bar. Default is the same as html_title. -#html_short_title = None - -# The name of an image file (relative to this directory) to place at the top -# of the sidebar. -#html_logo = None - -# 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 -# pixels large. -#html_favicon = None - -# Add any paths that contain custom static files (such as style sheets) here, -# relative to this directory. They are copied after the builtin static files, -# so a file named "default.css" will overwrite the builtin "default.css". -html_static_path = ['_static'] - -# If not '', a 'Last updated on:' timestamp is inserted at every page bottom, -# using the given strftime format. -#html_last_updated_fmt = '%b %d, %Y' - -# If true, SmartyPants will be used to convert quotes and dashes to -# typographically correct entities. -#html_use_smartypants = True - -# Custom sidebar templates, maps document names to template names. -#html_sidebars = {} - -# Additional templates that should be rendered to pages, maps page names to -# template names. -#html_additional_pages = {} - -# If false, no module index is generated. -#html_domain_indices = True - -# If false, no index is generated. -#html_use_index = True - -# If true, the index is split into individual pages for each letter. -#html_split_index = False - -# If true, links to the reST sources are added to the pages. -#html_show_sourcelink = True - -# If true, "Created using Sphinx" is shown in the HTML footer. Default is True. -#html_show_sphinx = True - -# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True. -#html_show_copyright = True - -# If true, an OpenSearch description file will be output, and all pages will -# contain a <link> tag referring to it. The value of this option must be the -# base URL from which the finished HTML is served. -#html_use_opensearch = '' - -# This is the file name suffix for HTML files (e.g. ".xhtml"). -#html_file_suffix = None - -# Output file base name for HTML help builder. -htmlhelp_basename = 'cliffdoc' - - -# -- Options for LaTeX output ------------------------------------------------ - -latex_elements = { - # The paper size ('letterpaper' or 'a4paper'). - #'papersize': 'letterpaper', - - # The font size ('10pt', '11pt' or '12pt'). - #'pointsize': '10pt', - - # Additional stuff for the LaTeX preamble. - #'preamble': '', -} - -# Grouping the document tree into LaTeX files. List of tuples -# (source start file, target name, title, author, -# documentclass [howto/manual]). -latex_documents = [ - ('index', 'cliff.tex', u'cliff Documentation', - u'Doug Hellmann', 'manual'), -] - -# The name of an image file (relative to this directory) to place at the top of -# the title page. -#latex_logo = None - -# For "manual" documents, if this is true, then toplevel headings are parts, -# not chapters. -#latex_use_parts = False - -# If true, show page references after internal links. -#latex_show_pagerefs = False - -# If true, show URL addresses after external links. -#latex_show_urls = False - -# Documents to append as an appendix to all manuals. -#latex_appendices = [] - -# If false, no module index is generated. -#latex_domain_indices = True - - -# -- Options for manual page output ------------------------------------------ - -# One entry per manual page. List of tuples -# (source start file, name, description, authors, manual section). -man_pages = [ - ('index', 'cliff', u'cliff Documentation', - [u'Doug Hellmann'], 1) -] - -# If true, show URL addresses after external links. -#man_show_urls = False - - -# -- Options for Texinfo output ---------------------------------------------- - -# Grouping the document tree into Texinfo files. List of tuples -# (source start file, target name, title, author, -# dir menu entry, description, category) -texinfo_documents = [ - ('index', 'cliff', u'cliff Documentation', - u'Doug Hellmann', 'cliff', 'One line description of project.', - 'Miscellaneous'), -] - -# Documents to append as an appendix to all manuals. -#texinfo_appendices = [] - -# If false, no module index is generated. -#texinfo_domain_indices = True - -# How to display URL addresses: 'footnote', 'no', or 'inline'. -#texinfo_show_urls = 'footnote' diff --git a/docs/source/demoapp.rst b/docs/source/demoapp.rst deleted file mode 100644 index 66e66cb..0000000 --- a/docs/source/demoapp.rst +++ /dev/null @@ -1,258 +0,0 @@ -======================== - Exploring the Demo App -======================== - -The cliff source package includes a ``demoapp`` directory containing -an example main program with several command plugins. - -Setup -===== - -To install and experiment with the demo app you should create a -virtual environment and activate it. This will make it easy to remove -the app later, since it doesn't do anything useful and you aren't -likely to want to hang onto it after you understand how it works. - -:: - - $ pip install virtualenv - $ virtualenv .venv - $ . .venv/bin/activate - (.venv)$ - -Next, install cliff in the same environment. - -:: - - (.venv)$ python setup.py install - -Finally, install the demo application into the virtual environment. - -:: - - (.venv)$ cd demoapp - (.venv)$ python setup.py install - -Usage -===== - -Both cliff and the demo installed, you can now run the command -``cliffdemo``. - -For basic command usage instructions and a list of the commands -available from the plugins, run:: - - (.venv)$ cliffdemo -h - -or:: - - (.venv)$ cliffdemo --help - -Run the ``simple`` command by passing its name as argument to ``cliffdemo``. - -:: - - (.venv)$ cliffdemo simple - -The ``simple`` command prints this output to the console: - -:: - - sending greeting - hi! - - -To see help for an individual command, use the ``help`` command:: - - (.venv)$ cliffdemo help files - -The Source -========== - -The ``cliffdemo`` application is defined in a ``cliffdemo`` package -containing several modules. - -main.py -------- - -The main application is defined in ``main.py``: - -.. literalinclude:: ../../demoapp/cliffdemo/main.py - :linenos: - -The :class:`DemoApp` class inherits from :class:`App` and overrides -:func:`__init__` to set the program description and version number. It -also passes a :class:`CommandManager` instance configured to look for -plugins in the ``cliff.demo`` namespace. - -The :func:`initialize_app` method of :class:`DemoApp` will be invoked -after the main program arguments are parsed, but before any command -processing is performed and before the application enters interactive -mode. This hook is intended for opening connections to remote web -services, databases, etc. using arguments passed to the main -application. - -The :func:`prepare_to_run_command` method of :class:`DemoApp` will be -invoked after a command is identified, but before the command is given -its arguments and run. This hook is intended for pre-command -validation or setup that must be repeated and cannot be handled by -:func:`initialize_app`. - -The :func:`clean_up` method of :class:`DemoApp` is invoked after a -command runs. If the command raised an exception, the exception object -is passed to :func:`clean_up`. Otherwise the ``err`` argument is -``None``. - -The :func:`main` function defined in ``main.py`` is registered as a -console script entry point so that :class:`DemoApp` can be run from -the command line (see the discussion of ``setup.py`` below). - -simple.py ---------- - -Two commands are defined in ``simple.py``: - -.. literalinclude:: ../../demoapp/cliffdemo/simple.py - :linenos: - -:class:`Simple` demonstrates using logging to emit messages on the -console at different verbose levels. - -:: - - (.venv)$ cliffdemo simple - sending greeting - hi! - - (.venv)$ cliffdemo -v simple - prepare_to_run_command Simple - sending greeting - debugging - hi! - clean_up Simple - - (.venv)$ cliffdemo -q simple - hi! - -:class:`Error` always raises a :class:`RuntimeError` exception when it -is invoked, and can be used to experiment with the error handling -features of cliff. - -:: - - (.venv)$ cliffdemo error - causing error - ERROR: this is the expected exception - - (.venv)$ cliffdemo -v error - prepare_to_run_command Error - causing error - ERROR: this is the expected exception - clean_up Error - got an error: this is the expected exception - - (.venv)$ cliffdemo --debug error - causing error - this is the expected exception - Traceback (most recent call last): - File ".../cliff/app.py", line 218, in run_subcommand - result = cmd.run(parsed_args) - File ".../cliff/command.py", line 43, in run - self.take_action(parsed_args) - File ".../demoapp/cliffdemo/simple.py", line 24, in take_action - raise RuntimeError('this is the expected exception') - RuntimeError: this is the expected exception - Traceback (most recent call last): - File "/Users/dhellmann/Envs/cliff/bin/cliffdemo", line 9, in <module> - load_entry_point('cliffdemo==0.1', 'console_scripts', 'cliffdemo')() - File ".../demoapp/cliffdemo/main.py", line 33, in main - return myapp.run(argv) - File ".../cliff/app.py", line 160, in run - result = self.run_subcommand(remainder) - File ".../cliff/app.py", line 218, in run_subcommand - result = cmd.run(parsed_args) - File ".../cliff/command.py", line 43, in run - self.take_action(parsed_args) - File ".../demoapp/cliffdemo/simple.py", line 24, in take_action - raise RuntimeError('this is the expected exception') - RuntimeError: this is the expected exception - -.. _demoapp-list: - -list.py -------- - -``list.py`` includes a single command derived from -:class:`cliff.lister.Lister` which prints a list of the files in the -current directory. - -.. literalinclude:: ../../demoapp/cliffdemo/list.py - :linenos: - -:class:`Files` prepares the data, and :class:`Lister` manages the -output formatter and printing the data to the console. - -:: - - (.venv)$ cliffdemo files - +---------------+------+ - | Name | Size | - +---------------+------+ - | build | 136 | - | cliffdemo.log | 2546 | - | Makefile | 5569 | - | source | 408 | - +---------------+------+ - - (.venv)$ cliffdemo files -f csv - "Name","Size" - "build",136 - "cliffdemo.log",2690 - "Makefile",5569 - "source",408 - -.. _demoapp-show: - -show.py -------- - -``show.py`` includes a single command derived from -:class:`cliff.show.ShowOne` which prints the properties of the named -file. - -.. literalinclude:: ../../demoapp/cliffdemo/show.py - :linenos: - -:class:`File` prepares the data, and :class:`ShowOne` manages the -output formatter and printing the data to the console. - -:: - - (.venv)$ cliffdemo file setup.py - +---------------+--------------+ - | Field | Value | - +---------------+--------------+ - | Name | setup.py | - | Size | 5825 | - | UID | 502 | - | GID | 20 | - | Modified Time | 1335569964.0 | - +---------------+--------------+ - - -setup.py --------- - -The demo application is packaged using distribute_, the modern -implementation of setuptools. - -.. literalinclude:: ../../demoapp/setup.py - :linenos: - -The important parts of the packaging instructions are the -``entry_points`` settings. All of the commands are registered in the -``cliff.demo`` namespace. Each main program should define its own -command namespace so that it only loads the command plugins that it -should be managing. - -.. _distribute: http://packages.python.org/distribute/ diff --git a/docs/source/developers.rst b/docs/source/developers.rst deleted file mode 100644 index ad02ee4..0000000 --- a/docs/source/developers.rst +++ /dev/null @@ -1,83 +0,0 @@ -================ - For Developers -================ - -If you would like to contribute to cliff directly, these instructions -should help you get started. Bug reports, and feature requests are -all welcome through the `Launchpad project`_. - -.. _Launchpad project: https://launchpad.net/python-cliff - -Changes to cliff should be submitted for review via the Gerrit tool, -following the workflow documented at -http://wiki.openstack.org/GerritWorkflow - -Pull requests submitted through GitHub will be ignored. - -Bugs should be filed under the `Launchpad project`_. - - -.. note:: - - Before contributing new features to clif core, please consider - whether they should be implemented as an extension instead. The - architecture is highly pluggable precisely to keep the core small. - -Building Documentation -====================== - -The documentation for cliff is written in reStructuredText and -converted to HTML using Sphinx. The build itself is driven by make. -You will need the following packages in order to build the docs: - -- Sphinx -- docutils - -Once all of the tools are installed into a virtualenv using -pip, run ``make docs`` to generate the HTML version of the -documentation:: - - $ make docs - (cd docs && make clean html) - sphinx-build -b html -d build/doctrees source build/html - Running Sphinx v1.1.3 - loading pickled environment... done - building [html]: targets for 1 source files that are out of date - updating environment: 1 added, 1 changed, 0 removed - reading sources... [100%] index - looking for now-outdated files... none found - pickling environment... done - done - preparing documents... done - writing output... [100%] index - writing additional files... genindex search - copying static files... done - dumping search index... done - dumping object inventory... done - build succeeded, 2 warnings. - - Build finished. The HTML pages are in build/html. - -The output version of the documentation ends up in -``./docs/build/html`` inside your sandbox. - -Running Tests -============= - -The test suite for clif uses tox_, which must be installed separately -(``pip install tox``). - -To run the tests under Python 2.7 and 3.3 as well as PyPy, run ``tox`` -from the top level directory of the git repository. - -To run tests under a single version of Python, specify the appropriate -environment when running tox:: - - $ tox -e py27 - -Add new tests by modifying an existing file or creating new script in -the ``tests`` directory. - -.. _tox: http://codespeak.net/tox - -.. _developer-templates: diff --git a/docs/source/history.rst b/docs/source/history.rst deleted file mode 100644 index e62752c..0000000 --- a/docs/source/history.rst +++ /dev/null @@ -1,163 +0,0 @@ -================= - Release History -================= - -dev - -- Fix the arguments passed to commands when they are instantiated to - pull out help. See https://github.com/dreamhost/cliff/issues/52 for - details. -- Add bash command completion. (Contributed by Terry Howe) -- Use stevedore to load formatter plugins. - -1.4.5 - -- Update the pyparsing dependency to a version that supports both - Python 2 and Python 3. -- Add PyPy testing. - -1.4.4 - -- Provide better error handling for unknown commands run from the - command line. (Contributed by Christophe Chauvet.) - -1.4.3 - -- More stdout encoding issues with Python 2.6. - -1.4.2 - -- Fix an issue with unicode output under Python 2.6. See - https://github.com/dreamhost/cliff/pull/40 for details. - -1.4.1 - -- Add ``dict2columns`` method to ``ShowOne``. (Contributed by Dean - Troyer) -- Pin the requirement for cmd2 more tightly. - -1.4 - -- Store a reference to the InteractiveApp on the App while in - interactive mode to allow commands to update the interactive - state. (Contributed by Tomaz Muraus) -- Remove reliance on distribute, now that it has merged with - setuptools 0.7. Providing an explicit dependency on setuptools - breaks updates in some cases, so just fail if it isn't there. - -1.3.3 - - - Restore compatibility with prettytable < 0.7.2 by forcing no - output if there is no data (instead of printing an empty - table). Contributed by Dirk Mueller. - - Update to allow cmd2 version 0.6.5.1. Contributed by Dirk Mueller. - -1.3.2 - - - Add ``convert_underscores`` parameter to ``CommandManager`` ``__init__`` - method to allow underscores to be used in command names. This optional - argument is defaulted to True to maintain current behavior. - (contributed by Joe Server) - - Use flake8_ for style checking. - - Relax version requirement for PrettyTable dependency to allow - point releases of 0.7. - -.. _flake8: https://pypi.python.org/pypi/flake8 - -1.3.1 - - - Sort list of commands in interactive help mode. (contributed by - Ilya Shakhat) - - Fix a dependency issue with PyParsing until the cmd2 package can - release an update setting the version of its dependency based on - the Python version. - -1.3 - - - Allow user to pass ``argparse_kwargs`` argument to the - ``build_option_parser`` method. This argument can contain extra - keyword arguments which are passed to the ``ArgumentParser`` constructor. - (contributed by Tomaz Muraus) - - Updated documentation to include dependency on distribute. - -1.2.1 - - - Fix problem with documentation packaging. - - Fix problem with missing ``izip`` import in ``lister.py``. - -1.2 - - - Fix problem with interactive mode ``help`` command. - - Disable logging by default but add a ``--log-file`` option to - re-enable it at runtime. - - Add support for python 2.6. (contributed by Mark McClain for - OpenStack Quantum) - -1.1.2 - - - Fix a packaging problem introduced in version 1.1. - -1.1 - - - Move tablib support (JSON, YAML, and HTML formatters) to a - separate project to comply with Ubuntu packaging requirements. See - https://github.com/dreamhost/cliff-tablib - -1.0 - - - Add trailing newlines after output from tablib-based formatters - (JSON, YAML, and HTML). Contributed by Matt Joyce. - - Some :pep:`8` fixes. - - Refactor the API in :class:`Command` to add :func:`take_action` - and make :func:`run` a concrete method. Existing users should only - need to rename :func:`run()` to :func:`take_action()` since the - function signatures have not changed. - - In :class:`Lister` and :class:`ShowOne` use :func:`take_action` - instead of :func:`get_data`. - -0.7 - - - Clean up interactive mode flag settting. - - Add support for Python 2.6, contributed by heavenshell. - - Fix multi-word commands in interactive mode. - -0.6 - - - Pass the non-global argument list to :func:`initialize_app` to be - used in initialization work. - -0.5.1 - - - Remove pinned version requirement for PrettyTable until the - OpenStack clients catch up to the API change. - -0.5 - - - Asking for help about a command by prefix lists all matching - commands. - - Add formatters for HTML, JSON, and YAML. - -0.4 - - - Add shell formatter for single objects. - - Add interactive mode. - - Expand documentation. - -0.3 - - - Add ShowOne base class for commands that show details about single - objects. - - Fix a problem with Lister when there is no data to be printed. - -0.2 - - - Incorporate changes from dtroyer to replace use of optparse in App - with argparse. - - Added "help" subcommand to replace ``--help`` option handling in - subcommands. - -0.1 - - - Initial public release. - - Included App, CommandManager, Lister, csv and table formatters, a - demo application, and basic documentation. diff --git a/docs/source/index.rst b/docs/source/index.rst deleted file mode 100644 index b474208..0000000 --- a/docs/source/index.rst +++ /dev/null @@ -1,33 +0,0 @@ -======================================================= - cliff -- Command Line Interface Formulation Framework -======================================================= - -cliff is a framework for building command line programs. It uses -plugins to define sub-commands, output formatters, and other -extensions. - -Contents: - -.. toctree:: - :maxdepth: 2 - - introduction - demoapp - list_commands - show_commands - complete - interactive_mode - classes - install - developers - history - - -Indices and tables -================== - -* :ref:`genindex` -* :ref:`modindex` -* :ref:`search` - -.. todolist:: diff --git a/docs/source/install.rst b/docs/source/install.rst deleted file mode 100644 index ad9a211..0000000 --- a/docs/source/install.rst +++ /dev/null @@ -1,51 +0,0 @@ -============== - Installation -============== - -Python Versions -=============== - -cliff is being developed under Python 2.7 and tested with Python 3.2. - -Dependencies -============ - -cliff depends on distribute_, the updated replacement for -setuptools. If you have an older version of setuptools installed, `you -may have trouble installing cliff`_ until you upgrade or set up a -virtualenv_ using distribute instead (by using ``--use-distribute``). - -.. _distribute: http://pypi.python.org/pypi/distribute - -.. _you may have trouble installing cliff: https://bitbucket.org/tarek/distribute/issue/91/install-glitch-when-using-pip-virtualenv - -.. _virtualenv: http://pypi.python.org/pypi/virtualenv - -.. _install-basic: - -Basic Installation -================== - -cliff should be installed into the same site-packages area where the -application and extensions are installed (either a virtualenv or the -global site-packages). You may need administrative privileges to do -that. The easiest way to install it is using pip_:: - - $ pip install cliff - -or:: - - $ sudo pip install cliff - -.. _pip: http://pypi.python.org/pypi/pip - -Source Code -=========== - -The source is hosted on github: https://github.com/dreamhost/cliff - -Reporting Bugs -============== - -Please report bugs through the github project: -https://github.com/dreamhost/cliff/issues diff --git a/docs/source/interactive_mode.rst b/docs/source/interactive_mode.rst deleted file mode 100644 index 519e89a..0000000 --- a/docs/source/interactive_mode.rst +++ /dev/null @@ -1,94 +0,0 @@ -================== - Interactive Mode -================== - -In addition to running single commands from the command line, cliff -supports an interactive mode in which the user is presented with a -separate command shell. All of the command plugins available from the -command line are automatically configured as commands within the -shell. - -Refer to the cmd2_ documentation for more details about features of -the shell. - -.. _cmd2: http://packages.python.org/cmd2/index.html - -.. todo:: Add details about configuring and interacting with the shell (copy from cmd2 docs) - -Example -======= - -The ``cliffdemo`` application enters interactive mode if no command is -specified on the command line. - -:: - - (.venv)$ cliffdemo - (cliffdemo) help - - Shell commands (type help <topic>): - =================================== - cmdenvironment edit hi l list pause r save shell show - ed help history li load py run set shortcuts - - Undocumented commands: - ====================== - EOF eof exit q quit - - Application commands (type help <topic>): - ========================================= - files help simple file error two part - -To obtain instructions for a built-in or application command, use the -``help`` command: - -:: - - (cliffdemo) help simple - usage: simple [-h] - - A simple command that prints a message. - - optional arguments: - -h, --help show this help message and exit - -The commands can be run, including options and arguments, as on the -regular command line: - -:: - - (cliffdemo) simple - sending greeting - hi! - (cliffdemo) files - +----------------------+-------+ - | Name | Size | - +----------------------+-------+ - | .git | 578 | - | .gitignore | 268 | - | .tox | 238 | - | .venv | 204 | - | announce.rst | 1015 | - | announce.rst~ | 708 | - | cliff | 884 | - | cliff.egg-info | 340 | - | cliffdemo.log | 2193 | - | cliffdemo.log.1 | 10225 | - | demoapp | 408 | - | dist | 136 | - | distribute_setup.py | 15285 | - | distribute_setup.pyc | 15196 | - | docs | 238 | - | LICENSE | 11358 | - | Makefile | 376 | - | Makefile~ | 94 | - | MANIFEST.in | 186 | - | MANIFEST.in~ | 344 | - | README.rst | 1063 | - | setup.py | 5855 | - | setup.py~ | 8128 | - | tests | 204 | - | tox.ini | 76 | - | tox.ini~ | 421 | - +----------------------+-------+ - (cliffdemo) diff --git a/docs/source/introduction.rst b/docs/source/introduction.rst deleted file mode 100644 index d9312b9..0000000 --- a/docs/source/introduction.rst +++ /dev/null @@ -1,64 +0,0 @@ -============== - Introduction -============== - -The cliff framework is meant to be used to create multi-level commands -such as subversion and git, where the main program handles some basic -argument parsing and then invokes a sub-command to do the work. - -Command Plugins -=============== - -Cliff takes advantage of Python's ability to load code dynamically to -allow the sub-commands of a main program to be implemented, packaged, -and distributed separately from the main program. This organization -provides a unified view of the command for *users*, while giving -developers the opportunity organize source code in any way they see -fit. - -Cliff Objects -============= - -Cliff is organized around four objects that are combined to create a -useful command line program. - -The Application ---------------- - -An :class:`cliff.app.App` is the main program that you run from the shell -command prompt. It is responsible for global operations that apply to -all of the commands, such as configuring logging and setting up I/O -streams. - -The CommandManager ------------------- - -The :class:`cliff.commandmanager.CommandManager` knows how to load -individual command plugins. The default implementation uses -`setuptools entry points`_ but any mechanism for loading commands can -be used by replacing the default :class:`CommandManager` when -instantiating an :class:`App`. - -The Command ------------ - -The :class:`cliff.command.Command` class is where the real work -happens. The rest of the framework is present to help the user -discover the command plugins and invoke them, and to provide runtime -support for those plugins. Each :class:`Command` subclass is -responsible for taking action based on instructions from the user. It -defines its own local argument parser (usually using argparse_) and a -:func:`take_action` method that does the appropriate work. - -The Interactive Application ---------------------------- - -The main program uses an :class:`cliff.interactive.InteractiveApp` -instance to provide a command-shell mode in which the user can type -multiple commands before the program exits. Many cliff-based -applications will be able to use the default implementation of -:class:`InteractiveApp` without subclassing it. - -.. _setuptools entry points: http://packages.python.org/distribute/setuptools.html - -.. _argparse: http://docs.python.org/library/argparse.html diff --git a/docs/source/list_commands.rst b/docs/source/list_commands.rst deleted file mode 100644 index 2be64e7..0000000 --- a/docs/source/list_commands.rst +++ /dev/null @@ -1,83 +0,0 @@ -=============== - List Commands -=============== - -One of the most common patterns with command line programs is the need -to print lists of data. cliff provides a base class for commands of -this type so that they only need to prepare the data, and the user can -choose from one of several output formatter plugins to see the list of -data in their preferred format. - -Lister -====== - -The :class:`cliff.lister.Lister` base class API extends -:class:`Command` to allow :func:`take_action` to return data to be -formatted using a user-selectable formatter. Subclasses should provide -a :func:`take_action` implementation that returns a two member tuple -containing a tuple with the names of the columns in the dataset and an -iterable that will yield the data to be output. See the description of -:ref:`the files command in the demoapp <demoapp-list>` for details. - -List Output Formatters -====================== - -cliff is delivered with two output formatters for list -commands. :class:`Lister` adds a command line switch to let the user -specify the formatter they want, so you don't have to do any extra -work in your application. - -csv ---- - -The ``csv`` formatter produces a comma-separated-values document as -output. CSV data can be imported into a database or spreadsheet for -further manipulation. - -:: - - (.venv)$ cliffdemo files -f csv - "Name","Size" - "build",136 - "cliffdemo.log",2690 - "Makefile",5569 - "source",408 - -table ------ - -The ``table`` formatter uses PrettyTable_ to produce output formatted -for human consumption. - -.. _PrettyTable: http://code.google.com/p/prettytable/ - -:: - - (.venv)$ cliffdemo files - +---------------+------+ - | Name | Size | - +---------------+------+ - | build | 136 | - | cliffdemo.log | 2546 | - | Makefile | 5569 | - | source | 408 | - +---------------+------+ - -Other Formatters ----------------- - -Formatters using tablib_ to produce JSON, YAML, and HTML are available -as part of `cliff-tablib`_. - -.. _cliff-tablib: https://github.com/dreamhost/cliff-tablib - -Creating Your Own Formatter ---------------------------- - -If the standard formatters do not meet your needs, you can bundle -another formatter with your program by subclassing from -:class:`cliff.formatters.base.ListFormatter` and registering the -plugin in the ``cliff.formatter.list`` namespace. - - -.. _tablib: https://github.com/kennethreitz/tablib diff --git a/docs/source/show_commands.rst b/docs/source/show_commands.rst deleted file mode 100644 index 87de6ff..0000000 --- a/docs/source/show_commands.rst +++ /dev/null @@ -1,89 +0,0 @@ -=============== - Show Commands -=============== - -One of the most common patterns with command line programs is the need -to print properties of objects. cliff provides a base class for -commands of this type so that they only need to prepare the data, and -the user can choose from one of several output formatter plugins to -see the data in their preferred format. - -ShowOne -======= - -The :class:`cliff.show.ShowOne` base class API extends -:class:`Command` to allow :func:`take_action` to return data to be -formatted using a user-selectable formatter. Subclasses should provide -a :func:`take_action` implementation that returns a two member tuple -containing a tuple with the names of the columns in the dataset and an -iterable that contains the data values associated with those -names. See the description of :ref:`the file command in the demoapp -<demoapp-show>` for details. - -Show Output Formatters -====================== - -cliff is delivered with output formatters for show -commands. :class:`ShowOne` adds a command line switch to let the user -specify the formatter they want, so you don't have to do any extra -work in your application. - -shell ------ - -The ``shell`` formatter produces output that can be parsed directly by -a typical UNIX shell as variable assignments. This avoids extra -parsing overhead in shell scripts. - -:: - - (.venv)$ cliffdemo file -f shell setup.py - name="setup.py" - size="5916" - uid="527" - gid="501" - modified_time="1335655655.0" - - (.venv)$ eval "$(cliffdemo file -f shell --prefix example_ setup.py)" - (.venv)$ echo $example_size - 5916 - -table ------ - -The ``table`` formatter uses PrettyTable_ to produce output -formatted for human consumption. - -.. _PrettyTable: http://code.google.com/p/prettytable/ - -:: - - (.venv)$ cliffdemo file setup.py - +---------------+--------------+ - | Field | Value | - +---------------+--------------+ - | Name | setup.py | - | Size | 5825 | - | UID | 502 | - | GID | 20 | - | Modified Time | 1335569964.0 | - +---------------+--------------+ - -Other Formatters ----------------- - -Formatters using tablib_ to produce JSON, YAML, and HTML are available -as part of `cliff-tablib`_. - -.. _cliff-tablib: https://github.com/dreamhost/cliff-tablib - -Creating Your Own Formatter ---------------------------- - -If the standard formatters do not meet your needs, you can bundle -another formatter with your program by subclassing from -:class:`cliff.formatters.base.ShowFormatter` and registering the -plugin in the ``cliff.formatter.show`` namespace. - - -.. _tablib: https://github.com/kennethreitz/tablib |