update documentation.

README.rst

@@ -19,6 +19,9 @@ Include tasks for:
 
 - pyflakes
 - coverage
+- sphinx documentation
+- PyPi package/documentation upload
+
 
 `docs`_ http://pythonhosted.org/doit-py
 

doc/dictionary.txt

@@ -1,10 +1,13 @@
 Config
 Indices
+PyPi
 Pyflakes
+PythonModule
 PythonPackage
 attrs
 autoattribute
 autoclass
+autofunction
 automodule
 bysource
 confclass
@@ -19,6 +22,9 @@ maxdepth
 modindex
 py
 pyflakes
+pypi
+pythonhosted
 quickstart
+sdist
 src
 toctree

doc/index.rst

@@ -3,6 +3,7 @@
    You can adapt this file completely to your liking, but it should at least
    contain the root `toctree` directive.
 
+
 ===================================
 doit-py -  documentation
 ===================================
@@ -15,10 +16,6 @@ Intro
 
 .. _doit: http://pydoit.org
 
-Include tasks for:
-
-- pyflakes
-- coverage
 
 
 Project Details
@@ -47,6 +44,11 @@ module: coverage
 
 .. automodule:: doitpy.coverage
 
+.. autoclass:: doitpy.coverage.PythonModule
+   :members: __init__
+   :member-order: bysource
+
+
 .. autoclass:: doitpy.coverage.PythonPackage
    :members: __init__, all_modules
    :member-order: bysource
@@ -62,15 +64,23 @@ module: coverage
 
 
 
-.. toctree::
-   :maxdepth: 2
+module: docs
+==================
+
+.. automodule:: doitpy.docs
+
+.. autofunction:: doitpy.docs.spell
 
+.. autofunction:: doitpy.docs.sphinx
 
+.. autofunction:: doitpy.docs.pythonhosted_upload
 
-Indices and tables
+
+module: pypi
 ==================
 
-* :ref:`genindex`
-* :ref:`modindex`
-* :ref:`search`
+.. automodule:: doitpy.pypi
 
+.. autoclass:: doitpy.pypi.PyPi
+   :members: __init__, git_manifest, sdist_upload
+   :member-order: bysource

dodo.py

@@ -21,7 +21,8 @@ def task_test():
     return {'actions': ['py.test']}
 
 def task_coverage():
-    cov = Coverage([PythonPackage('doitpy', test_path='tests')])
+    cov = Coverage([PythonPackage('doitpy', test_path='tests')],
+                   config={'branch':False})
     yield cov.all()
     yield cov.src()
     yield cov.by_module()

doitpy/coverage.py

@@ -9,8 +9,8 @@
     def task_coverage():
         """show coverage for all modules including tests"""
         cov = Coverage([PythonPackage('my_pkg_name', 'tests')],
-                       config=Config(branch=False, parallel=True,
-                                     omit=['tests/no_cover.py'],)
+                       config={'branch':False, 'parallel':True,
+                               'omit': ['tests/no_cover.py']},
                        )
         yield cov.all() # create task `coverage`
         yield cov.src() # create task `coverage_src`
@@ -39,8 +39,17 @@ def all_modules(self):
 
 
 class PythonModule(PythonFiles):
-    """reference to a single python module / test for the module"""
+    """reference to a single python module / test for the module
+
+    :ivar list-str src: list of path of source modules
+    :ivar list-str test: list of path of all modules from test folder
+
+    """
     def __init__(self, path, test_path):
+        """
+        :param str/pathlib.Path path: path to python module.
+        :param str/pathlib.Path test_path: path to module with tests.
+        """
         self.src = [path]
         self.test = [test_path]
 

doitpy/docs.py

@@ -1,3 +1,21 @@
+"""create tasks related to documentation generation
+
+Example to create tasks to:
+ - spell check all restructured text files (including README)
+ - build sphinx docs in `doc` folder
+ - upload built sphinx docs to `pythonhosted` using `setuptools`
+
+::
+
+    def task_docs():
+        doc_files = glob.glob('doc/*.rst') + ['README.rst']
+        yield docs.spell(doc_files, 'doc/dictionary.txt')
+        yield docs.sphinx('doc/', 'doc/_build/html/', task_dep=['spell'])
+        yield docs.pythonhosted_upload('doc/_build/html/', task_dep=['sphinx'])
+
+
+"""
+
 import subprocess
 
 def check_no_output(doc_file, dictionary):
@@ -22,8 +40,8 @@ def check_no_output(doc_file, dictionary):
 def spell(files, dictionary):
     """spell checker for doc files
 
-    :param files list-str: list of files to spell check
-    :param dictionary str: path of dictionary with extra words
+    :param list-str files: list of files to spell check
+    :param str dictionary: path of dictionary with extra words
     """
     for doc_file in files:
         yield {
@@ -37,7 +55,12 @@ def spell(files, dictionary):
 
 # task creator
 def sphinx(root_path, build_path, task_dep=None):
-    """build sphinx docs"""
+    """build sphinx docs
+
+    :param str root_path: root path of sphinx docs
+    :param str build_path: path generated sphinx docs will be saved in
+    :param list-str task_dep: list of tasks this task will depend on
+    """
     cmd = "sphinx-build -b html -d %s_build/doctrees %s %s"
     action = cmd % (root_path, root_path, build_path)
     # sphinx has its own check it up-to-date so we dont care
@@ -56,8 +79,8 @@ def sphinx(root_path, build_path, task_dep=None):
 def pythonhosted_upload(www_path, task_dep):
     """deploy website (sphinx docs)
 
-    :param www_path str: path to folder containig www files
-    :param task_dep list-str: name of task that build the docs
+    :param str www_path: path to folder containig www files
+    :param list-str task_dep: list of tasks this task will depend on
     """
     action = "python setup.py upload_docs --upload-dir %s"
     yield {

doitpy/pypi.py

@@ -1,4 +1,17 @@
+"""create task to upload project to PyPi
 
+Example:
+ - create a `MANIFEST` file with all tracked files in a git repo
+ - upload an `sdist` package
+
+::
+
+    def task_pypi():
+        pkg = PyPi()
+        yield pkg.git_manifest()
+        yield pkg.sdist_upload()
+
+"""
 
 class PyPi(object):
     """helper to create tasks to upload a python package to PyPi"""