Metadata-Version: 1.1
Name: pyjig
Version: 1.0.9
Summary: Quickly create python projects from templates.
Home-page: https://github.com/jamercee/pyjig
Author: Jim Carroll
Author-email: jim@carroll.net
License: Pyjig is licensed under the 3-clause BSD License
Download-URL: https://github.com/jamercee/pyjig
Description: :mod:`pyjig` - Quickly create python projects from templates
        ################################################################
        
        .. module:: pyjig
           :synopsis: Quickly create python projects from templates
        .. moduleauthor:: Jim Carroll <jim@carroll.net>
        
        Pyjig quickly creates new python projects using pre-created templates. Projects
        can be simple scripts, distutils packages or full blown applications.  Pyjig
        can even add python source modules to existing projects.
        
        Pyjig is a wrapper around `Cookiecutter <http://cookiecutter.rtfd.org>`_,
        which is a command-line utility that creates projects from ``cookiecutters``
        (project templates). Templates are downloaded from public repos (such as
        github.com and bitbucket.org). Templates are written in `Jinja
        <http://jina.pocoo.org>`_.
        
        Pyjig uses three public repos:
        
        +---------------------------------------------------+----------------------------------+
        | Repo                                              | Description                      |
        +===================================================+==================================+
        | https://github.org/jamercee/cookiecutter-pyapp    | Python application type projects |
        +---------------------------------------------------+----------------------------------+
        | https://github.org/jamercee/cookiecutter-pypkg    | Python package type projects     |
        +---------------------------------------------------+----------------------------------+
        | https://github.org/jamercee/cookiecutter-pysource | Crete python source file(s)      |
        +---------------------------------------------------+----------------------------------+
        
        Project Motivation
        ------------------
        
        Using python requires developers to employ a full ecosystem of tools. At
        Carroll-Net, all projects require the following tools; `pylint
        <http://www.pylint.org>`_ and `flake8 <https://pypi.python.org/pypi/flake8>`_
        for static code analysis, `sphinx <http://sphinx-doc.org>`_ for project
        documents and `git <http://git-scm.com>`_ for revision control.  And this
        requires setting up directories, config files, a unittest infrastructure and a
        comprehensive Makefile for automating the daily build, test and install tasks.
        
        With all these steps, it's easy to miss one, or to make a typo when copying
        from another project which then causes developers to spend time debugging.
        What was needed was a way to ensure uniform deployment and configuration of our
        python architecture and toolchain.
        
        Project Layout
        --------------
        
        Each new project will create the following directories and files::
        
           myproj               Project root
           +
           |
           |   .gitignore
           |   id.txt
           |   Makefile
           |   pylint.rc
           |   setup.cfg
           |   setup.py
           |
           +---.git             Git repository
           |       ...
           |
           +---docs             Sphinx documentation
           |       conf.py
           |       index.rst
           |       make.bat
           |       Makefile
           |
           +---src              Project source code
           |   \---myproj
           |           __init__.py
           |
           \---tests            Unittest infrastructure
                   __init__.py
        
        Makefile generation
        -------------------
        
        Each project will have a customized ``Makefile`` installed in the project's
        root directory. It's syntax is written to support `GNU Make
        <http://gnu.org/software/make>`_. It comes with the following pre-built recipes
        
        +-------------+-----------------------------------------------------------------------+
        | Recipe      | Description                                                           |
        +=============+=======================================================================+
        | comp        | Perform static analysis (default target)                              |
        +-------------+-----------------------------------------------------------------------+
        | tests       | Run unittests                                                         |
        +-------------+-----------------------------------------------------------------------+
        | docs        | Generate html documentation                                           |
        +-------------+-----------------------------------------------------------------------+
        | dist        | Build python package                                                  |
        +-------------+-----------------------------------------------------------------------+
        | install     | Perform static analysis, run unittests and install to site-packages   |
        +-------------+-----------------------------------------------------------------------+
        | viewdocs    | Rebuild html docs & launch browser                                    |
        +-------------+-----------------------------------------------------------------------+
        | clean       | Meta-recipe to invoke ``clean-build``, ``clean-pyc``, ``clean-docs``  |
        +-------------+-----------------------------------------------------------------------+
        | clean-build | Remove all built outputs                                              |
        +-------------+-----------------------------------------------------------------------+
        | clean-pyc   | Remove python built elements (\*.pyc, \*.pyo, etc...)                 |
        +-------------+-----------------------------------------------------------------------+
        | debug       | Generate Makefile diagnostic output                                   |
        +-------------+-----------------------------------------------------------------------+
        | help        | Display Makefile help                                                 |
        +-------------+-----------------------------------------------------------------------+
        
        
        Static Analysis
        ---------------
        
        Python's flexible syntax means that coding errors are difficult to detect until
        runtime. Static analysis tries to solve this by scanning code for coding
        errors, bugs and bad style. It is an invaluable technique that has saved us
        untold hours in debugging.
        
        We first started using `pylint <http://www.pylint.org>`_. Then later on we
        added a second static analysis tool `flake8
        <https://pypi.python.org/pypi/flake8>`_. Each tool has it's strengths and we've
        found the combination of both has provided material reduction in time spent
        debugging.
        
        Each of these two tools requires some tweaking before they will generate useful
        advice.  Pyjig will handle configuring sane defaults for new projects to get
        them up to speed quickly.
        
        To perform static analysis of code, from within the project's root folder run
        ``make comp``.
        
        .. note::
        
           The ``Makefile`` recipe detects changes in ``*.py`` with reference to ``*.pyc``.
           If the ``*.pyc`` is missing or older than it's ``*.py``, a static analysis
           pass will be done, and if the pass does not generate errors or warnings, the
           ``*.pyc`` will be re-built.
        
        Code Documentation
        ------------------
        
        Carroll-Net has adopted `Sphinx <http://sphinx-doc.org>`_ as our documentation
        generator for python projects. Sphinx converts `reStructuredText
        <https://en.wikipedia.org/wiki/ReStructuredText>`_ into HTML websites. Sphinx
        can extract documentation from source modules and automatically generate
        browesable websites.
        
        There are two Makefile recipes related to documentation; ``make docs`` which
        will rebuild documentation and ``make viewdocs`` which will rebuild docs and
        launch a webbrowser to read the rebuilt docs.
        
        Two good references for authoring reST documents are
        
           * https://docs.python.org/devguide/documenting.html
           * https://pythonhosted.org/an_example_pypi_project/sphinx.html
        
        Verision Control
        ----------------
        
        Carroll-Net has adopted `Git <http://git-scm.org>`_ as our version control
        system for software. Git is a fast, reliable distributed revision control
        system. Originally developed for Linux kernel development it is now the most
        widely used source code management tool.
        
        Pyjig will initialize a git repository for each new project it creates using
        your local sytem defaults (see `git config ...
        <http://git-scm.com/book/en/v2/Customizing-Git-Git-Configuration>`_.). And each
        time you use Pyjig to add python source to an existing project, pyjig will add
        the source to the repo.
        
        Pyjig will not create the repo is invoked with ``--excludegit`` or of the
        dirctory is a subdirectory of an existing git repository. It detects
        repository membership by invoking `git status
        <http://git-scm.com/docs/git-status>`_.
        
        Pyjig Name
        ----------
        
        Pyjig borrows it's name from the concept of a jig which is a tool used in metal
        and woodworking. A jig is a template that allows one to make duplicates of
        pieces.  The simplest example is a key duplication machine, which uses one key
        as the guide to make copies.
        
        Command line options
        ********************
        
        *usage:* ``pyjig  [-?] [-d] [--pkg PKG] [--app APP] [-x] [source [source ..]]``
        
        Positional arguments
        ====================
        
        .. option:: source
        
           Add one or more source file(s) to project. If the current directry is not part of an
           existing project, the source file will be created, but no project related activities
           will be taken (no unittest generation, no sphix-docs generation, not added to git...)
        
        Optional argument:
        ==================
        
        .. option:: ?, -h, --help
        
           Display help and exit
        
        .. option:: -d, --debug
        
           Generate diagnotic output.
        
        .. option:: --pkg PKG
        
           Create a distutils package project.
        
        .. option:: --app APP
        
           Create an application type project.
        
        .. option:: -x, --excludegit
        
           Do not initialize git repo and do not add new source to git repo.
        
        ..
           Copyright(c), 2015, Carroll-Net, Inc., All Rights Reserved.
Platform: any
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: BSD License
Classifier: Natural Language :: English
Classifier: Operating System :: OS Independent
Classifier: Topic :: Software Development :: Build Tools
Classifier: Topic :: System :: Software Distribution
