Added some more doc

inclement · inclement · commit 3981103a5771 · 2015-06-28T14:49:21.000+01:00
diff --git a/doc/source/commands.rst b/doc/source/commands.rst
@@ -4,3 +4,47 @@ Commands
 
 This page documents all the commands and options that can be passed to
 toolchain.py.
+
+
+Main commands
+-------------
+
+.. autoclass:: toolchain.ToolchainCL
+   :members:
+
+
+General arguments
+-----------------
+
+These arguments may be passed to any command in order to modify its behaviour.
+
+``--debug``
+  Print extra debug information about the build, including all compilation output.
+
+
+Distribution arguments
+----------------------
+
+p4a supports several arguments used for specifying which compiled
+Android distribution you want to use. You may pass any of these
+arguments to any command, and if a distribution is required they will
+be used to load, or compile, or download this as necessary.
+
+None of these options are essential, and in principle you need only
+supply those that you need.
+
+
+``--name NAME``
+  The name of the distribution. Only one distribution with a given name can be created.
+
+``--requirements LIST,OF,REQUIREMENTS`` 
+  The recipes that your
+  distribution must contain, as a comma separated list. These must be
+  names of recipes or the pypi names of Python modules.
+
+``--force_build BOOL``
+  Whether the distribution must be compiled from scratch.
+
+.. note:: These options are preliminary. Others will include toggles
+          for allowing downloads, and setting additional directories
+          from which to load user dists.
diff --git a/doc/source/conf.py b/doc/source/conf.py
@@ -21,6 +21,7 @@
 # documentation root, use os.path.abspath to make it absolute, like shown here.
 #sys.path.insert(0, os.path.abspath('.'))
 sys.path.append(os.path.abspath('ext/sphinx_rtd_theme'))
+sys.path.append(os.path.abspath('../../pythonforandroid'))
 
 import sphinx_rtd_theme
 
diff --git a/doc/source/recipes.rst b/doc/source/recipes.rst
@@ -14,5 +14,91 @@ compiled components; if you just want to build an APK, you can jump
 straight to the :doc:`quickstart` or :doc:`commands` documentation, or
 can use the :code:`recipes` command to list available recipes. 
 
-This page describes how recipes work, and how to make your own.
+
+Creating your own Recipe
+------------------------
+
+This documentation jumps straight to the practicalities of creating
+your own recipe. The formal reference documentation of the Recipe
+class can be found in the `Recipe class <recipe_class_>`_ section and below.
+
+The basic declaration of a recipe is as follows::
+
+  class YourRecipe(Recipe):
+
+      url = 'http://example.com/example-{version}.tar.gz'
+      version = '2.0.3'
+      md5sum = '4f3dc9a9d857734a488bcbefd9cd64ed'
+
+      depends = ['kivy', 'sdl2']  # These are just examples
+      conflicts = ['pygame'] 
+
+See the `Recipe class documentation <recipe_class_>`_ for full
+information about each parameter.
+
+These core options are vital for all recipes, though the url may be
+omitted if the source is somehow loaded from elsewhere.
+
+.. note:: The url includes the ``{version}`` tag. You should only
+          access the url with the ``versioned_url`` property, which
+          replaces this with the version attribute.
+
+The actual build process takes place via three core methods::
+
+      def prebuild_arch(self, arch):
+          super(YourRecipe, self).prebuild_arch(arch)
+          # Do any pre-initialisation
+
+      def build_arch(self, arch):
+          super(YourRecipe, self).build_arch(arch)
+          # Do the main recipe build
+         
+      def postbuild_arch(self, arch):
+          super(YourRecipe, self).build_arch(arch)
+          # Do any clearing up
+
+The prebuild of every recipe is run before the build of any recipe,
+and likewise the build of every recipe is run before the postbuild of
+any. This lets you strictly order the build process.
+
+If you defined an url for your recipe, you do *not* need to manually
+download it, this is handled automatically.
+
+The recipe will automatically be built in a special isolated build
+directory, which you can access with
+:code:`self.get_build_dir(arch.arch)`. You should only work within
+this directory. It may be convenient to use the ``current_directory``
+context manager defined in toolchain.py::
+
+  from toolchain import current_directory
+  def build_arch(self, arch):
+      super(YourRecipe, self).build_arch(arch)
+      with current_directory(self.get_build_dir(arch.arch)):
+          with open('example_file.txt', 'w'):
+              fileh.write('This is written to a file within the build dir')
+  
+The argument to each method, ``arch``, is an object relating to the
+architecture currently being built for. You can mostly ignore it,
+though may need to use the arch name ``arch.arch``.
+          
+.. note:: You can also implement arch-specific versions of each
+          method, which are called (if they exist) by the superclass,
+          e.g. ``def prebuild_armeabi(self, arch)``.
+
+
+.. _recipe_class:
+
+
+The ``Recipe`` class
+--------------------
+
+The ``Recipe`` is the base class for all p4a recipes. The core
+documentation of this class is given below, followed by discussion of
+how to create your own Recipe subclass.
+
+.. autoclass:: toolchain.Recipe
+   :members:
+   :member-order: = 'bysource'
+
+
 
diff --git a/pythonforandroid/toolchain.py b/pythonforandroid/toolchain.py
@@ -684,8 +684,8 @@ def get_distribution(cls, ctx, name=None, recipes=[], allow_download=True,
             if force_build:
                 continue
             if (set(dist.recipes) == set(recipes) or
-                (set(recipes).issubset(set(dist.recipes) and not require_perfect_match))):
-                info('{} has exactly the right recipes, using this one')
+                (set(recipes).issubset(set(dist.recipes)) and not require_perfect_match)):
+                info('{} has exactly the right recipes, using this one'.format(dist.name))
                 return dist
 
         assert len(possible_dists) < 2
@@ -894,33 +894,57 @@ def get_bootstrap(cls, name, ctx):
 
 
 class Recipe(object):
-    version = None
     url = None
+    '''The address from which the recipe may be downloaded. This is not
+    essential, it may be omitted if the source is available some other
+    way, such as via the :class:`IncludedFilesBehaviour` mixin.
+
+    If the url includes the version, you may (and probably should)
+    replace this with ``{version}``, which will automatically be
+    replaced by the :attr:`version` string during download.
+
+    .. note:: Methods marked (internal) are used internally and you
+              probably don't need to call them, but they are available
+              if you want.
+    '''
+
+    version = None
+    '''A string giving the version of the software the recipe describes,
+    e.g. ``2.0.3`` or ``master``.'''
+
+    
     md5sum = None
+    '''The md5sum of the source from the :attr:`url`. Non-essential, but
+    you should try to include this, it is used to check that the download
+    finished correctly.
+    '''
+    
     depends = []
+    '''A list containing the names of any recipes that this recipe depends on.
+    '''
+    
     conflicts = []
-
-    name = None  # name for the recipe dir
+    # AND: Not currently used
+    '''A list containing the names of any recipes that are known to be
+    incompatible with this one.'''
+    
+    # name = None  # name for the recipe dir
 
     archs = ['armeabi']  # will android use this?
 
-    # library = None
-    # libraries = []
-    # include_dir = None
-    # include_per_arch = False
-    # frameworks = []
-    # sources = []
 
     @property
     def versioned_url(self):
+        '''A property returning the url of the recipe with ``{version}``
+        replaced by the :attr:`url`. If accessing the url, you should use this
+        property, *not* access the url directly.'''
         if self.url is None:
             return None
         return self.url.format(version=self.version)
 
-    # API available for recipes
     def download_file(self, url, filename, cwd=None):
         """
-        Download an `url` to `outfn`
+        (internal) Download an ``url`` to a ``filename``.
         """
         if not url:
             return
@@ -944,7 +968,7 @@ def report_hook(index, blksize, size):
 
     def extract_file(self, filename, cwd):
         """
-        Extract the `filename` into the directory `cwd`.
+        (internal) Extract the `filename` into the directory `cwd`.
         """
         if not filename:
             return
@@ -961,7 +985,7 @@ def extract_file(self, filename, cwd):
             zf.close()
 
         else:
-            warning("Error: cannot extract, unreconized extension for {}".format(
+            warning("Error: cannot extract, unrecognized extension for {}".format(
                 filename))
             raise Exception()
 
@@ -1206,25 +1230,25 @@ def get_recipe_env(self, arch=None):
     #         self.ctx.state[key] = value
     #     return value
 
-    def execute(self):
-        if self.custom_dir:
-            self.ctx.state.remove_all(self.name)
-        self.download()
-        self.extract()
-        self.build_all()
+    # def execute(self):
+    #     if self.custom_dir:
+    #         self.ctx.state.remove_all(self.name)
+    #     self.download()
+    #     self.extract()
+    #     self.build_all()
 
     # AND: Will need to change how this works
-    @property
-    def custom_dir(self):
-        """Check if there is a variable name to specify a custom version /
-        directory to use instead of the current url.
-        """
-        d = environ.get("P4A_{}_DIR".format(self.name.lower()))
-        if not d:
-            return
-        if not exists(d):
-            return
-        return d
+    # @property
+    # def custom_dir(self):
+    #     """Check if there is a variable name to specify a custom version /
+    #     directory to use instead of the current url.
+    #     """
+    #     d = environ.get("P4A_{}_DIR".format(self.name.lower()))
+    #     if not d:
+    #         return
+    #     if not exists(d):
+    #         return
+    #     return d
 
     # def prebuild(self):
     #     self.prebuild_arch(self.ctx.archs[0])  # AND: Need to change
@@ -1738,6 +1762,7 @@ def dist_from_args(ctx, dist_args):
 def split_argument_list(l):
     return re.split(r'[ ,]*', l)
 
+
 class ToolchainCL(object):
     def __init__(self):
         parser = argparse.ArgumentParser(
@@ -1926,13 +1951,14 @@ def create(self, args):
 
         print('dists are', Distribution.get_distributions(ctx))
         dist = dist_from_args(ctx, self.dist_args)
-        info('Ready to create dist {}, contains recipes {}'.format(
-            dist.name, ', '.join(dist.recipes)))
         if not dist.needs_build:
-            info('This dist already exists! If you dont\'t want to use '
-                 'it, you must delete it and rebuild with the new set of '
-                 'recipes, or create your new dist with a different name.')
+            info('You asked to create a distribution, but a dist with this name '
+                 'already exists. If you don\'t want to use '
+                 'it, you must delete it and rebuild, or create your '
+                 'new dist with a different name.')
             exit(1)
+        info('Ready to create dist {}, contains recipes {}'.format(
+            dist.name, ', '.join(dist.recipes)))
 
         bs = Bootstrap.get_bootstrap(args.bootstrap, ctx)
         info_main('# Creating dist with with {} bootstrap'.format(bs.name))
