Permalink
Browse files

update api documentation

  • Loading branch information...
1 parent 6fe31bc commit 628b7122859a9b7950c2b52af784fb98b7b323f9 @domenkozar committed Jan 2, 2013
Showing with 43 additions and 14 deletions.
  1. +4 −0 docs/source/api.rst
  2. +9 −7 docs/source/index.rst
  3. +29 −6 mrbob/configurator.py
  4. +1 −1 mrbob/hooks.py
View
@@ -1,6 +1,10 @@
Source documentation
====================
+.. warning::
+ Python API is far from being "frozen", use it with zero backwards-compatibility in mind.
+ You are welcome to report suggestions to bug tracker.
+
:mod:`mrbob` -- Main package
****************************
View
@@ -58,13 +58,15 @@ Glossary
.. glossary::
-`dotted notation`
- Importable Python function specified with dots as importing a module separated with a column
- to denote a function. For example *mrbob.rendering:render_structure*
-`mr.bob`
- This section configures how `mrbob` behaves
-`variables`
- This section answers to the questions that will be passed to templates for rendering
+ dotted notation
+ Importable Python function specified with dots as importing a module separated with a column
+ to denote a function. For example *mrbob.rendering:render_structure*
+
+ mr.bob
+ This section configures how `mrbob` behaves
+
+ variables
+ This section answers to the questions that will be passed to templates for rendering
Indices and tables
View
@@ -113,15 +113,22 @@ def parse_template(template_name):
class Configurator(object):
- """Controller that figures out settings and renders file structure.
+ """Controller that figures out settings, asks questions and renders
+ the directory structure.
:param template: Template name
:param target_directory: Filesystem path to a output directory
:param bobconfig: Configuration for mr.bob behaviour
- :param variables: Given variables
+ :param variables: Given variables to questions
+ :param defaults: Overriden defaults of the questions
- TODO: describe what configurator does
- TODO: display api variables
+ Additional to above settings, `Configurator` exposes following attributes:
+
+ - :attr:`template_dir` is root directory of the template
+ - :attr:`is_tempdir` if template directory is temporary (when using zipfile)
+ - :attr:`templateconfig` dictionary parsed from `template` section
+ - :attr:`questions` ordered list of `Question instances to be asked
+ - :attr:`bobconfig` dictionary parsed from `mrbob` section of the config
"""
@@ -224,9 +231,22 @@ def ask_questions(self):
class Question(object):
- """Question configuration. Parameters are used to configure validation of the answer.
+ """Question configuration. Parameters are used to configure questioning
+ and possible validation of the answer.
+
+ :param name: Unique, namespaced name of the question
+ :param question: Question to be asked
+ :param default: Default value of the question
+ :param required: Is question required?
+ :type required: bool
+ :param command_prompt: Function to executed to ask the question given question text
+ :param help: Optional help message
+ :param pre_ask_question: Space limited functions in dotted notation to ask before the question is asked
+ :param post_ask_question: Space limited functions in dotted notation to ask aster the question is asked
+ :param **extra: Any extra parameters stored for possible extending of `Question` functionality
+
+ Any of above parameters can be accessed as an attribute of `Question` instance.
- TODO: parameters
"""
def __init__(self,
@@ -255,6 +275,9 @@ def __repr__(self):
def ask(self, configurator):
"""Eventually, ask the question.
+
+ :param configurator: :class:`mrbob.configurator.Configurator` instance
+
"""
correct_answer = None
self.default = configurator.defaults.get(self.name, self.default)
View
@@ -1,4 +1,4 @@
-"""Use any of hooks below or write your own."""
+"""Use any of hooks below or write your own. You are welcome to contribute them!"""
from .configurator import ValidationError

0 comments on commit 628b712

Please sign in to comment.