Merge pull request #17 from takluyver/docs-work

Create docs about traitlets

.gitignore

@@ -3,9 +3,6 @@ build
 dist
 _build
 docs/man/*.gz
-docs/source/api/generated
-docs/source/config/options
-docs/source/interactive/magics-generated.txt
 docs/gh-pages
 IPython/html/notebook/static/mathjax
 IPython/html/static/style/*.map

docs/requirements.txt

@@ -0,0 +1 @@
+ipython_genutitls

docs/source/conf.py

@@ -40,6 +40,7 @@
 extensions = [
     'sphinx.ext.autodoc',
     'sphinx.ext.intersphinx',
+    'sphinx.ext.napoleon',
 ]
 
 # Add any paths that contain templates here, relative to this directory.

docs/source/index.rst

@@ -4,9 +4,17 @@ Traitlets
 :Release: |release|
 :Date: |today|
 
-Building applications with :mod:`traitlets.config`:
+Traitlets is a framework that lets Python classes have attributes with type
+checking, dynamically calculated default values, and 'on change' callbacks.
+
+The package also includes a mechanism to use traitlets for configuration,
+loading values from files or from command line arguments. This is a distinct
+layer on top of traitlets, so you can use traitlets in your code without using
+the configuration machinery.
 
 .. toctree::
     :maxdepth: 2
-
-    config.rst
+
+    using_traitlets
+    trait_types
+    config

docs/source/trait_types.rst

@@ -0,0 +1,112 @@
+Trait Types
+===========
+
+.. module:: traitlets
+
+.. class:: TraitType
+
+   The base class for all trait types.
+
+   .. automethod:: __init__
+
+Numbers
+-------
+
+.. class:: Integer
+
+   An integer trait. On Python 2, this automatically uses the ``int`` or
+   ``long`` types as necessary.
+
+.. class:: Int
+.. class:: Long
+
+   On Python 2, these are traitlets for values where the ``int`` and ``long``
+   types are not interchangeable. On Python 3, they are both aliases for
+   :class:`Integer`.
+
+   In almost all situations, you should use :class:`Integer` instead of these.
+
+.. autoclass:: Float
+
+.. autoclass:: Complex
+
+.. class:: CInt
+           CLong
+           CFloat
+           CComplex
+
+   Casting variants of the above. When a value is assigned to the attribute,
+   these will attempt to convert it by calling e.g. ``value = int(value)``.
+
+Strings
+-------
+
+.. autoclass:: Unicode
+
+.. autoclass:: Bytes
+
+.. class:: CUnicode
+           CBytes
+
+   Casting variants. When a value is assigned to the attribute, these will
+   attempt to convert it to their type. They will not automatically encode/decode
+   between unicode and bytes, however.
+
+.. autoclass:: ObjectName
+
+.. autoclass:: DottedObjectName
+
+Containers
+----------
+
+.. autoclass:: List
+   :members: __init__
+
+.. autoclass:: Set
+   :members: __init__
+
+.. autoclass:: Tuple
+   :members: __init__
+
+.. autoclass:: Dict
+   :members: __init__
+
+Classes and instances
+---------------------
+
+.. autoclass:: Instance
+   :members: __init__
+
+.. autoclass:: Type
+   :members: __init__
+
+.. autoclass:: This
+
+.. autoclass:: ForwardDeclaredInstance
+
+.. autoclass:: ForwardDeclaredType
+
+
+Miscellaneous
+-------------
+
+.. autoclass:: Bool
+
+.. class:: CBool
+
+   Casting variant. When a value is assigned to the attribute, this will
+   attempt to convert it by calling ``value = bool(value)``.
+
+.. autoclass:: Enum
+
+.. autoclass:: CaselessStrEnum
+
+.. autoclass:: TCPAddress
+
+.. autoclass:: CRegExp
+
+.. autoclass:: Union
+   :members: __init__
+
+.. autoclass:: Any
+

docs/source/using_traitlets.rst

@@ -0,0 +1,68 @@
+Using Traitlets
+===============
+
+.. currentmodule:: traitlets
+
+Any class with traitlet attributes must inherit from :class:`HasTraits`.
+
+.. autoclass:: HasTraits
+
+   .. automethod:: trait_names
+
+   .. automethod:: class_trait_names
+
+   .. automethod:: traits
+
+   .. automethod:: class_traits
+
+   .. automethod:: trait_metadata
+
+   .. automethod:: add_trait
+
+You then declare the traitlets on the class like this::
+
+    from traitlets import HasTraits, Int, Unicode
+
+    class Requester(HasTraits):
+        url = Unicode()
+        timeout = Int(30)  # 30 will be the default value
+
+For the available traitlet types and the arguments you can give them, see
+:doc:`trait_types`.
+
+Dynamic default values
+----------------------
+
+To calculate a default value dynamically, give your class a method named
+:samp:`_{traitname}_default`. This will be called on the instance,
+and should return the default value. For example::
+
+    import getpass
+
+    class Identity(HasTraits):
+        username = Unicode()
+        def _username_default(self):
+            return getpass.getuser()
+
+Callbacks when traitlets change
+-------------------------------
+
+To do something when a traitlet is changed, define a method named
+:samp:`_{traitname}_changed`. This can have several possible signatures:
+
+.. class:: TraitletsCallbacksExample
+
+   .. method:: _traitlet1_changed()
+               _traitlet2_changed(traitlet_name)
+               _traitlet3_changed(traitlet_name, new_value)
+               _traitlet4_changed(traitlet_name, old_value, new_value)
+
+You can also add callbacks to a trait dynamically:
+
+.. automethod:: HasTraits.on_trait_change
+
+.. note::
+
+   If a traitlet with a dynamic default value has another value set before it is
+   used, the default will not be calculated.
+   Any callbacks on that trait will will fire, and *old_value* will be ``None``.