add best practices

docs/dev_guide.rst

@@ -3,12 +3,17 @@ Developer's Guide
 
 
 .. toctree::
-   :maxdepth: 1
+   :maxdepth: 2
    :caption: Table of Contents
    :glob:
 
    dev_guide/data_structures
-   dev_guide/data_structures
+   dev_guide/best_practices
+   dev_guide/custom_modules
+   dev_guide/custom_field
+   dev_guide/custom_data_loader
+   dev_guide/custom_web_services
+
 
 
 

docs/dev_guide/best_practices.rst

@@ -0,0 +1,64 @@
+Module Development Best Practice
+================================
+
+
+If you create custom Tripal Modules, here are some best practices and suggestions.
+
+The Drupal Devel Module
+=======================
+
+
+Before staring your development work, it is suggested that you download and install the `Drupal devel module <https://drupal.org/project/devel>`_. This module helps greatly with debugging your custom theme or module. A very useful function of this module is the dpm function. You can use the dpm function to print to the web page an interactive view of the contents of any variable. This can be extremely helpful when accessing Chado data in objects and arrays returned by Tripal.
+
+Add your module to Tripal.info
+==============================
+
+Do your best to list and upate your modules at http://tripal.info/extensions.
+
+
+Coding Best Practices
+=======================
+
+Host your code on GitHub
+-------------------------
+
+We recommend making your code open source and hosting it on GitHub. It’s free, it let’s people easily find, use, and contribute to your source code.
+
+Associate the GitHub repository with Tripal
+---------------------------------------------
+
+Once your module is on GitHub, consider joining the Tripal organization. Your lab group can exist as a team and maintain control over your code, but your projects will be listed in the main Tripal group.
+
+If you’d rather not, you can still tag your project as Tripal by clicking on the Manage Topics Link at the top of your repository.
+
+DOIs
+--------
+
+When your module is release ready, why not create a Digital Object Identifier (DOI) for it with `Zenodo <https://zenodo.org/>`_? It’s free! Sync your github account and create a new release (Zenodo won’t find old releases). You can then display your DOI badge on your module’s page.
+
+Additionally, there is a `Tripal Community group <https://zenodo.org/communities/tripal/>`_ on Zenodo. You can edit your record to associate your DOI with the Tripal community.
+
+Testing and Continuous Integration
+-----------------------------------
+
+`Tripal Test Suite <https://github.com/statonlab/TripalTestSuite>`_ is a full-featured testing module that makes writing tests much easier. which will automatically set up a PHPUnit and Travis testing environment for you.
+
+* Test with PHPUnit
+* Run tests as you push code with Travis CI
+
+
+Documentation
+--------------
+
+Every repository can include a README file that will be displayed on the repository page. A README file should at a minimum include:
+
+* An overview of the module
+* Instructions on how to install & use the module
+
+Consider documenting your Code itself. Tripal documents in the `Doxygen style <http://www.stack.nl/~dimitri/doxygen/>`_ which allows documentation webpages to be automatically generated. Even if you don’t build HTML documentation, the in-line code documentation will be very helpful to contributors.
+
+Coding Standards
+-----------------
+
+Drupal has defined `coding standards <https://www.drupal.org/docs/develop/standards/coding-standards>`_ that Tripal modules should meet.
+

docs/dev_guide/data_structures.rst

@@ -17,7 +17,7 @@ The following figure describes the heirarchical relationship between Drupal Enti
    :alt: Entity terminology guide
 
 
-Furthermore, fields are "attached" to a Bundle and hold unique values for each Entity. The following figure describes this relationship for a Gene Bundle that has several fields attached: name, description and organism.  Note that in this figure the Entity and each of the Fields are defined using a controlled vocabulary term.  As a result, bundles and fields can be described using the Semantic Web concepts of a "subject", "predicate" and "object".  We will discuss more on controlled vocabularies a bit later in the Handbook.
+Furthermore, fields are "attached" to a Bundle and hold unique values for each Entity. The following figure describes this relationship for a Gene Bundle that has several fields attached: name, description and organism.  Note that in this figure the Entity and each of the Fields are defined using a controlled vocabulary term.  As a result, bundles and fields can be described using the `Semantic Web <https://en.wikipedia.org/wiki/Semantic_Web>`_ concepts of a "subject", "predicate" and "object".  We will discuss more on controlled vocabularies a bit later in the Handbook.
 
 
 
@@ -44,7 +44,7 @@ An entity is a discrete data record.  Entities are most commonly seen as "pages"
 Fields
 =======
 
-A field is a reusable "data container" that is attached to a Bundle. Programmatically, each field provides one or more primitive data types, with validators and widgets for editing and formatters for display. Each field independently manages the data to which it assigned.  Just like with Bundles, Fields are also described using controlled vocabulary terms.  For example, a gene Bundle has a field attached that provides the name of the gene.   This field only provides the name and nothing more.  Tripal uses the schema:name vocabulary term to describe the field.  
+A field is a reusable "data container" that is attached to a Bundle. Programmatically, each field provides one or more primitive data types, with validators and widgets for editing and formatters for display. Each field independently manages the data to which it assigned.  Just like with Bundles, Fields are also described using controlled vocabulary terms.  For example, a gene Bundle has a field attached that provides the name of the gene.   This field only provides the name and nothing more.  Tripal uses the `schema:name <http://schema.org/name>`_ vocabulary term to describe the field.  
 
 Field Instances
 ================