diff --git a/Makefile b/Makefile index 21e6d91..2bb0bef 100644 --- a/Makefile +++ b/Makefile @@ -17,8 +17,13 @@ lint: .PHONY: clean clean: - rm -vrf build ./*.pyc see/*.pyc __pycache__ see/__pycache__ .eggs + rm -vrf build docs/_build + rm -vrf ./*.pyc see/*.pyc __pycache__ see/__pycache__ .eggs .PHONY: dist dist: python3 setup.py sdist --formats=bztar,gztar,zip + +.PHONY: docs +docs: + (cd docs && make html) diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 0000000..79f52d9 --- /dev/null +++ b/docs/Makefile @@ -0,0 +1,20 @@ +# Minimal makefile for Sphinx documentation +# + +# You can set these variables from the command line. +SPHINXOPTS = +SPHINXBUILD = python3 -msphinx +SPHINXPROJ = see +SOURCEDIR = . +BUILDDIR = _build + +# Put it first so that "make" without argument is like "make help". +help: + @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + +.PHONY: help Makefile + +# Catch-all target: route all unknown targets to Sphinx using the new +# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). +%: Makefile + @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) diff --git a/docs/api.rst b/docs/api.rst new file mode 100644 index 0000000..5f248cd --- /dev/null +++ b/docs/api.rst @@ -0,0 +1,15 @@ +API +=== + +.. module:: see + + +``see`` function +---------------- + +The ``see`` function is designed for the interactive Python interpreter. +Import it by running:: + + >>> from see import see + +.. autofunction:: see diff --git a/docs/conf.py b/docs/conf.py new file mode 100644 index 0000000..8c9e44e --- /dev/null +++ b/docs/conf.py @@ -0,0 +1,191 @@ +#!/usr/bin/env python3 +# -*- coding: utf-8 -*- +# +# see documentation build configuration file, created by +# sphinx-quickstart on Sat May 20 09:46:19 2017. +# +# 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. + +# 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 os +import sys +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.doctest', + 'sphinx.ext.coverage', + 'sphinx.ext.githubpages', +] + +# Add any paths that contain templates here, relative to this directory. +templates_path = ['_templates'] + +# The suffix(es) of source filenames. +# You can specify multiple suffix as a list of string: +# +# source_suffix = ['.rst', '.md'] +source_suffix = '.rst' + +# The master toctree document. +master_doc = 'index' + +# General information about the project. +project = 'see' +copyright = '2009-2017, Liam Cooke' +author = 'Liam Cooke' + +# 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 = '1.4.0a0' +# 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. +# +# This is also used if you do content translation via gettext catalogs. +# Usually you set "language" from the command line for these cases. +language = None + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +# This patterns also effect to html_static_path and html_extra_path +exclude_patterns = [ + '_build', 'Thumbs.db', '.DS_Store', +] + +# The name of the Pygments (syntax highlighting) style to use. +pygments_style = 'sphinx' + +# If true, `todo` and `todoList` produce output, else they produce nothing. +todo_include_todos = False + + +# -- 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 = 'alabaster' + +# 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 = { + # This value must end with a trailing slash. + #'canonical_url': '', + + 'github_user': 'araile', + 'github_repo': 'see', +} + +# 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'] + + +# -- Options for HTMLHelp output ------------------------------------------ + +# Output file base name for HTML help builder. +htmlhelp_basename = 'seedoc' + + +# -- 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': '', + + # Latex figure (float) alignment + # + # 'figure_align': 'htbp', +} + +# Grouping the document tree into LaTeX files. List of tuples +# (source start file, target name, title, +# author, documentclass [howto, manual, or own class]). +latex_documents = [ + (master_doc, 'see.tex', 'see Documentation', + 'Liam Cooke', 'manual'), +] + + +# -- Options for manual page output --------------------------------------- + +# One entry per manual page. List of tuples +# (source start file, name, description, authors, manual section). +man_pages = [ + (master_doc, 'see', 'see Documentation', + [author], 1) +] + + +# -- 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 = [ + (master_doc, 'see', 'see Documentation', + author, 'see', 'One line description of project.', + 'Miscellaneous'), +] + + + +# -- Options for Epub output ---------------------------------------------- + +# Bibliographic Dublin Core info. +epub_title = project +epub_author = author +epub_publisher = author +epub_copyright = copyright + +# The unique identifier of the text. This can be a ISBN number +# or the project homepage. +# +# epub_identifier = '' + +# A unique identification for the text. +# +# epub_uid = '' + +# A list of files that should not be packed into the epub file. +epub_exclude_files = ['search.html'] + + diff --git a/docs/index.rst b/docs/index.rst new file mode 100644 index 0000000..7f36538 --- /dev/null +++ b/docs/index.rst @@ -0,0 +1,75 @@ +.. see documentation master file. + This should contain the root `toctree` directive. + +.. For Python examples, use the following: + * 64-column terminal + * sys.ps1 = '>>> ' + * sys.ps2 = '... ' + + +see: dir for humans +=================== + +.. module:: see + + +Release v\ |release|. + +.. image:: https://travis-ci.org/araile/see.svg?branch=develop + :target: https://travis-ci.org/araile/see + +.. image:: https://coveralls.io/repos/github/araile/see/badge.svg?branch=develop + :target: https://coveralls.io/github/araile/see?branch=develop + +**see** is a friendly alternative to the ``dir`` function in Python. +It shows you a summary of what you can do with an object. + +Supports Python 2.6+ and 3.3+. Also works in iPython and PyPy. + + +See in action +------------- + +Compare the following:: + + >>> dir([]) + ['__add__', '__class__', '__contains__', '__delattr__', '__delit + em__', '__dir__', '__doc__', '__eq__', '__format__', '__ge__', ' + __getattribute__', '__getitem__', '__gt__', '__hash__', '__iadd_ + _', '__imul__', '__init__', '__init_subclass__', '__iter__', '__ + le__', '__len__', '__lt__', '__mul__', '__ne__', '__new__', '__r + educe__', '__reduce_ex__', '__repr__', '__reversed__', '__rmul__ + ', '__setattr__', '__setitem__', '__sizeof__', '__str__', '__sub + classhook__', 'append', 'clear', 'copy', 'count', 'extend', 'ind + ex', 'insert', 'pop', 'remove', 'reverse', 'sort'] + +:: + + >>> see([]) + [] in + += * + *= < <= == != + > >= dir() hash() + help() iter() len() repr() + reversed() str() .append() .clear() + .copy() .count() .extend() .index() + .insert() .pop() .remove() .reverse() + .sort() + + +Contents +-------- + +.. toctree:: + :maxdepth: 2 + + install + api + license + + +Indices and tables +------------------ + +- :ref:`genindex` +- :ref:`modindex` +- :ref:`search` diff --git a/docs/install.rst b/docs/install.rst new file mode 100644 index 0000000..68733f4 --- /dev/null +++ b/docs/install.rst @@ -0,0 +1,15 @@ +Installation +============ + +The latest release can be found on the +`Python Package Index `_. + + +Install with Pip +---------------- + +To install **see**, run the following command in your terminal:: + + pip3 install -U see + +For Python 2, change ``pip3`` to ``pip2``. diff --git a/docs/license.rst b/docs/license.rst new file mode 100644 index 0000000..16ca462 --- /dev/null +++ b/docs/license.rst @@ -0,0 +1,32 @@ +Licensing Information +===================== + +**see** is licensed under the BSD 3-Clause License. + +Copyright (c) 2009-2017, Liam Cooke. +All rights reserved. + +Redistribution and use in source and binary forms, with or without +modification, are permitted provided that the following conditions are met: + +* Redistributions of source code must retain the above copyright notice, this + list of conditions and the following disclaimer. + +* Redistributions in binary form must reproduce the above copyright notice, + this list of conditions and the following disclaimer in the documentation + and/or other materials provided with the distribution. + +* Neither the name of the copyright holder nor the names of its + contributors may be used to endorse or promote products derived from + this software without specific prior written permission. + +THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE +DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE +FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR +SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER +CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, +OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. diff --git a/requirements.txt b/requirements.txt index 1617288..5c9b0cf 100644 --- a/requirements.txt +++ b/requirements.txt @@ -5,4 +5,5 @@ coverage>=4.0.0 pep8>=1.5.0 pyflakes>=1.0.0 +sphinx>=1.6.0 unittest2>=1.1.0 diff --git a/see/inspector.py b/see/inspector.py index 5b9daba..b967f53 100644 --- a/see/inspector.py +++ b/see/inspector.py @@ -72,20 +72,27 @@ def see(obj=DEFAULT_ARG, pattern=None, r=None): Keyword arguments (all optional): - obj object to be inspected - pattern shell-style search pattern (e.g. '*len*') - r regular expression - - If obj is omitted, objects in the current scope are listed instead. - - Some unique symbols are used:: - - .* implements obj.anything - [] implements obj[key] - in implements membership tests (e.g. x in obj) - +obj unary positive operator (e.g. +2) - -obj unary negative operator (e.g. -2) - ? raised an exception + * ``obj`` -- the object to be inspected. If this is omitted, the objects in + the current scope are shown instead. + + * ``pattern`` -- filter the results with a shell-style search pattern + (e.g. ``'*len*'``). + + * ``r`` -- filter the results with a regular expression + (e.g. ``'get|set'``). + + Some special symbols are included in the output from ``see``: + + ``.*`` + implements obj.anything + ``[]`` + implements obj[key] + ``in`` + implements membership tests (e.g. x in obj) + ``+obj`` + unary positive operator (e.g. +2) + ``-obj`` + unary negative operator (e.g. -2) """ use_locals = obj is DEFAULT_ARG