Merge lp:~oemedical-commiter/oemedical/trunk-ImprovingDocs into lp:oemedical

[Nhomar - Vauxoo]

Some improvement in doc.
Create minimal structure, some work to do yet.
Just to be sure it is merged, befoce continue with documentation process.

=== modified file 'oemedical/oemedical_appointment/oemedical_appointment.py'
--- oemedical/oemedical_appointment/oemedical_appointment.py	2012-12-01 10:08:17 +0000
+++ oemedical/oemedical_appointment/oemedical_appointment.py	2012-12-03 07:05:27 +0000
@@ -25,7 +25,7 @@
 
 class OeMedicalAppointment(osv.osv):
     _name = 'oemedical.appointment'
-
+    _description = 'Appointments in OeMedical'
     _columns = {
         'consultations': fields.many2one('product.product',
                                          string='Consultation Services', ),
@@ -56,6 +56,4 @@
          'name': lambda obj, cr, uid, context: 
             obj.pool.get('ir.sequence').get(cr, uid, 'oemedical.appointment'),
                  }
-
-OeMedicalAppointment()
 # vim:expandtab:smartindent:tabstop=4:softtabstop=4:shiftwidth=4:

=== modified file 'web_doc_oemedical/controllers/main.py'
--- web_doc_oemedical/controllers/main.py	2012-12-02 05:23:06 +0000
+++ web_doc_oemedical/controllers/main.py	2012-12-03 07:05:27 +0000
@@ -30,9 +30,7 @@
     '''
     whereami=os.path.dirname(os.path.realpath(__file__))
     
-    f = open(os.path.join("%s/../_build/html/%s"%(whereami, name), "r")
-    html = f.read()
-    return html
+    return ''
 
 
 class OeMedicalDoc(web.http.Controller):

=== added file 'web_doc_oemedical/doc/_static/icon-sidebar.png'
Binary files web_doc_oemedical/doc/_static/icon-sidebar.png	1970-01-01 00:00:00 +0000 and web_doc_oemedical/doc/_static/icon-sidebar.png	2012-12-03 07:05:27 +0000 differ
=== added file 'web_doc_oemedical/doc/_static/icon.png'
Binary files web_doc_oemedical/doc/_static/icon.png	1970-01-01 00:00:00 +0000 and web_doc_oemedical/doc/_static/icon.png	2012-12-03 07:05:27 +0000 differ
=== modified file 'web_doc_oemedical/doc/_templates/sidebarintro.html'
--- web_doc_oemedical/doc/_templates/sidebarintro.html	2012-12-02 05:06:35 +0000
+++ web_doc_oemedical/doc/_templates/sidebarintro.html	2012-12-03 07:05:27 +0000
@@ -1,16 +1,21 @@
-<p class="logo"><a href="http://doc.openerp.com/">
-  <img class="logo" src="{{ pathto('_static/openerp.png', 1) }}" alt="Logo"/>
-</a></p>
-
-<h3>Other Docs</h3>
-<ul>
-  <li><a href="http://doc.openerp.com/trunk/developers">OpenERP Developers Documentation</a></li>
-  <li><a href="http://doc.openerp.com/trunk/developers/web">OpenERP Web Developers Documentation</a></li>
-  <li><a href="http://doc.openerp.com/trunk/users">OpenERP Users Documentation</a></li>
-</ul>
-
 <h3>Useful Links</h3>
 <ul>
+  <li><a href="http://www.oemedical.org/">OeMedical Community Site</a></li>
   <li><a href="http://www.openerp.com/">The OpenERP website</a></li>
   <li><a href="http://python.org/">The Python programming language</a></li>
 </ul>
+<h3>External Docs</h3>
+<p>
+You must have this docs present to understand the OeMedical Documentation.
+</p>
+<ul>
+  <li><a href="http://doc.openerp.com/trunk/developers">OpenERP Developers</a></li>
+  <li><a href="http://doc.openerp.com/trunk/developers/web">OpenERP Web Developers</a></li>
+  <li><a href="http://doc.openerp.com/trunk/users">OpenERP Users</a></li>
+  <li><a href="http://doc.openerp.com/v6.1/contribute/index.html#how-to-contribute-link">OpenERP Community</a></li>
+  <li><a href="http://doc.openerp.com/v6.1/usability_book/index.html#usability-link">Useability Guidelines</a></li>
+</ul>
+<h4>Social Networks</h4>
+<a class="twitter-timeline" data-dnt=true href="https://twitter.com/oemedicalteam" data-widget-id="275457328831139840">Tweets by @oemedicalteam</a>
+<script>!function(d,s,id){var js,fjs=d.getElementsByTagName(s)[0];if(!d.getElementById(id)){js=d.createElement(s);js.id=id;js.src="//platform.twitter.com/widgets.js";fjs.parentNode.insertBefore(js,fjs);}}(document,"script","twitter-wjs");</script>
+

=== modified file 'web_doc_oemedical/doc/_templates/sidebarlogo.html'
--- web_doc_oemedical/doc/_templates/sidebarlogo.html	2012-12-02 05:06:35 +0000
+++ web_doc_oemedical/doc/_templates/sidebarlogo.html	2012-12-03 07:05:27 +0000
@@ -1,3 +0,0 @@
-<p class="logo"><a href="{{ pathto(master_doc) }}">
-  <img class="logo" src="{{ pathto('_static/openerp.png', 1) }}" alt="Logo"/>
-</a></p>

=== modified file 'web_doc_oemedical/doc/_themes/flask/theme.conf'
--- web_doc_oemedical/doc/_themes/flask/theme.conf	2012-12-02 05:06:35 +0000
+++ web_doc_oemedical/doc/_themes/flask/theme.conf	2012-12-03 07:05:27 +0000
@@ -4,6 +4,6 @@
 pygments_style = flask_theme_support.FlaskyStyle
 
 [options]
-index_logo = ''
-index_logo_height = 120px
+index_logo = 'icon.png'
+index_logo_height = 60px
 touch_icon = 

=== modified file 'web_doc_oemedical/doc/api_oemedical_index.rst'
--- web_doc_oemedical/doc/api_oemedical_index.rst	2012-12-02 05:06:35 +0000
+++ web_doc_oemedical/doc/api_oemedical_index.rst	2012-12-03 07:05:27 +0000
@@ -1,3 +1,9 @@
 ============================
 OeMedical API Documentation.
 ============================
+
+.. autoclass:: oemedical_appointment.OeMedicalAppointment
+  :special-members: __all__
+
+.. autoclass:: oemedical_patient.OeMedicalPatient
+  :special-members: __all__

=== modified file 'web_doc_oemedical/doc/conf.py'
--- web_doc_oemedical/doc/conf.py	2012-12-02 05:06:35 +0000
+++ web_doc_oemedical/doc/conf.py	2012-12-03 07:05:27 +0000
@@ -17,8 +17,20 @@
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
 #sys.path.insert(0, os.path.abspath('.'))
+#Necesary to import osv.osv in autodoc
+SERVERPATH = "/home/nhomar/instancias/7.0/server/openerp"
+#Necesary to import openerp in autodoc
+OPENERPPATH = "/home/nhomar/instancias/7.0/server"
+#OeMEdical Relative path.
+OEMEDICALPATH = '../../oemedical'
 sys.path.append(os.path.abspath('_themes'))
 sys.path.append(os.path.abspath('..'))
+sys.path.append(SERVERPATH)
+sys.path.append(OPENERPPATH)
+#sys.path.append(os.path.abspath(OEMEDICALPATH))
+for oemModule in os.listdir(OEMEDICALPATH):
+    sys.path.append(os.path.join(OEMEDICALPATH,oemModule))
+
 #Uncomment this line to include all models and methods documentations
 #sys.path.append(os.path.abspath('../model'))
 
@@ -31,6 +43,8 @@
 # coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
 extensions = ['sphinx.ext.autodoc', 'sphinx.ext.intersphinx', 'sphinx.ext.todo', 'sphinx.ext.viewcode']
 
+autodoc_default_flags = ['members', 'undoc-members', 'linenos']
+
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
 
@@ -115,6 +129,7 @@
 # The name of an image file (relative to this directory) to place at the top
 # of the sidebar.
 #html_logo = None
+html_logo = 'icon-sidebar.png'
 
 # The name of an image file (within the static path) to use as favicon of the
 # docs.  This file should be a Windows icon file (.ico) being 16x16 or 32x32

=== added file 'web_doc_oemedical/doc/contribute.rst'
--- web_doc_oemedical/doc/contribute.rst	1970-01-01 00:00:00 +0000
+++ web_doc_oemedical/doc/contribute.rst	2012-12-03 07:05:27 +0000
@@ -0,0 +1,184 @@
+.. sectnum::
+    :start: 1
+
+All the coding guidelines of OeMEdical is based on 
+`OpenERP guidelines for coding.`_
+
+Some exceptions in Styles are in this code that you must to follow to approve 
+`merge proposals`_ and ensure the quality of the system.
+
+Coding Styles
++++++++++++++
+
+What will be considered good or bad code to merge in core.
+
+Your code should be pep8 compliant.
+-----------------------------------
+
+In order to be sure our code is of high wuality, is important use some 
+conventions in the python world the most accepted is the `pep8 convention`_, 
+we will use it in this project.
+
+If you develop in a linux enviroment you can install ``pep8`` program:
+
+.. code-block:: guess
+
+  sudo apt-get install pep8
+  
+With this program you will be able to test your code before the `merge proposals`_
+or even test the code of other person to help us to answer with Q&A reasons 
+before commit or merge changes.
+
+i.e:
+
+.. code-block:: guess
+  
+  pep8 yourpythonfile.py
+  
+It will return a set of results about the quality of your code see 
+``pep8 --help`` for more information.
+
+About new objects
+-----------------
+
+A new object is this one that for functional or design reasons is not included 
+on the core of OpenERP.
+
+New classes signature.
+''''''''''''''''''''''
+
+All new classes must start with ``OeMedicalName`` see it in `CamelCase`.
+
+i.e.:
+
+.. literalinclude:: snnipets/snnipets.py
+  :lines: 2
+
+New Object name.
+''''''''''''''''
+
+All new objects will complay with OpenERP standard it means separated by one dot
+between words.
+
+i.e.
+
+.. literalinclude:: snnipets/snnipets.py
+  :lines: 15
+
+New method signature.
+'''''''''''''''''''''
+
+All new methods will be named with `snake_case`.
+
+File management for new objects
+'''''''''''''''''''''''''''''''
+
+All new objects will be in a new folder, with both xml and py files, see 
+``oemedical`` modules for some example.
+
+About Openerp Version.
+----------------------
+
+In version 1.0 of OeMedical we decide work with version 7.0 of OpenERP, for 
+this reason some specific conventions must be verified.
+
+Views 7.0 compatibles.
+''''''''''''''''''''''
+
+All views that use OeMedical will comply with version 7.0 of OpenERP.
+
+About Data for Standards.
+-------------------------
+
+Data loaded should be in an extra module called oemedical_yourstandard_data, 
+to separate data errors from model errors, frequently data dont change too much, 
+because it is based on Standards.
+
+.. warning::
+
+  If the data is necesary for the correct work of your module this rule 
+  do not apply
+
+About Complementary Modules.
+----------------------------
+
+Modules that improve functionality working with the core of openerp, should be 
+in an extra module, it means.
+
+i.e:
+
+* Creation of Automated invoices and commercial management: oemedical_account
+* Relation with sale orders: oemedical_sale
+* Relation with purchase: oemedical_purchase
+
+Avoid use names not self descriptive, as `oemedical_purchase_ext`, the correct 
+sufix should say what it is improving.
+
+Useability Guidelines.
+----------------------
+
+If a model is inherited, we should create them own view with them own action, 
+to be sure the user is able to use this model in its functional context without 
+unnecesary information in this function.
+
+Technical requirements.
+-----------------------
+
+If a model impact some kind of a more than 3 steps flow, the object ``MUST`` have 
+Workflow.
+
+Documentation Guidelines
+++++++++++++++++++++++++
+
+In order to be sure the useabilty and to avoid not re-use the job of others 
+members of community will not be merged any module or improvement that is not 
+correct documented.
+
+How Documentation will be included.
+-----------------------------------
+
+All documentation will be in a web_doc_yourmodule module to be able to embed documentation compiled with sphinx in the same server.
+
+.. note::
+
+  TODO: Put some example or link to a branch with a basic template for this 
+  kind of module.
+
+Guidelines to document your improvement.
+----------------------------------------
+
+We must try to document following `pep-0257 convention`_.
+
+As the standard is a little extense we share some useful snnipets, with some 
+examples.
+
+.. literalinclude:: snnipets/snnipets.py
+  :lines: 48-66
+
+It is important understand that the documentation with pep standards just 
+propose some good practices from the technical point of view, to be sure all 
+is correct and all community involved has the correct approach about what 
+document and how, some premises are listed below, and the community can propose 
+another ones to follow, in the middle this methodology can be reviewed and 
+improved.
+
+About comments in code:
+-----------------------
+
+At least the model is still on development, we must avoid code commented, 
+all commentaries must be usuables by sphinx to use `autodoc`_ embebed.
+
+Try to commit with a really `explicit`_ message to avoid unecessary comments
+
+.. footer::
+
+ All discussion regading this guidelines is in Launchpad on this topic, you can 
+ collaborate in this `discussion`_
+
+.. _pep-0257 convention: http://www.python.org/dev/peps/pep-0257/
+.. _OpenERP guidelines for coding.: http://doc.openerp.com/v6.1/contribute/15_guidelines/coding_guidelines.html
+.. _merge proposals: https://help.launchpad.net/Code/Review?action=show&redirect=BranchMergeProposals
+.. _explicit: http://doc.openerp.com/v6.1/contribute/15_guidelines/coding_guidelines_framework.html#bazaar-is-your-historian
+.. _pep8 convention: http://www.python.org/dev/peps/pep-0008/
+.. _autodoc: http://sphinx-doc.org/ext/autodoc.html#directive-autoattribute
+.. _discussion: https://blueprints.launchpad.net/oemedical/+spec/coding-guidelines

=== modified file 'web_doc_oemedical/doc/index.rst'
--- web_doc_oemedical/doc/index.rst	2012-12-02 05:06:35 +0000
+++ web_doc_oemedical/doc/index.rst	2012-12-03 07:05:27 +0000
@@ -32,6 +32,14 @@
 OeMedical API.
 ''''''''''''''
 
+Coding Guidelines
++++++++++++++++++
+
+.. toctree::
+    :maxdepth: 2
+
+    contribute.rst
+ 
 .. toctree::
     :maxdepth: 2
 

=== added directory 'web_doc_oemedical/doc/snnipets'
=== added file 'web_doc_oemedical/doc/snnipets/snnipets.py'
--- web_doc_oemedical/doc/snnipets/snnipets.py	1970-01-01 00:00:00 +0000
+++ web_doc_oemedical/doc/snnipets/snnipets.py	2012-12-03 07:05:27 +0000
@@ -0,0 +1,80 @@
+# -*- encoding: utf-8 -*-
+class OeMedicalAppointment(osv.osv):
+    '''
+    DocString for a new object.
+    Is important say here where will be the menu to test this object.
+    Mention the reason whay it was created, if it is necesary link 
+    some `external <http://externaldoc.com>`_
+    especitication about why it was created.
+    
+    Probably, there an object on OpenERP base that already comply with your 
+    needs and in this case it will be easyiest to propose a redisign of the 
+    feature, or propose a better solution, in other hand it can be used as 
+    reference for other features if it is documented enought.
+    '''
+    _name = 'oemedical.appointment'
+    _description = 'Appointments in OeMedical'
+    _columns = {
+        'consultations': fields.many2one('product.product',
+                                         string='Consultation Services', ),
+        'patient': fields.many2one('oemedical.patient', string='Patient', 
+                                   required=True, select=True),
+        'name': fields.char(size=256, string='Appointment ID', readonly=True),
+        'appointment_date': fields.datetime(string='Date and Time'),
+        'doctor': fields.many2one('oemedical.physician',
+                                  string='Physician',select=True),
+        'comments': fields.text(string='Comments'),
+        'appointment_type': fields.selection([
+            ('ambulatory', 'Ambulatory'),
+            ('outpatient', 'Outpatient'),
+            ('inpatient', 'Inpatient'),
+        ], string='Type'),
+        'institution': fields.many2one('res.partner',
+                                       string='Health Center', ),
+        'urgency': fields.selection([
+            ('a', 'Normal'),
+            ('b', 'Urgent'),
+            ('c', 'Medical Emergency'), ],
+            string='Urgency Level'),
+        'speciality': fields.many2one('oemedical.specialty',
+                                      string='Specialty', ),
+    }
+    
+    _defaults = {
+         'name': lambda obj, cr, uid, context: 
+            obj.pool.get('ir.sequence').get(cr, uid, 'oemedical.appointment'),
+                 }
+
+def test_method(self, cr, uid, ids, context=None):
+    '''Something in doc
+    
+    :param context['mail']: 'new' to send a new mail or 'reply' 
+    :type context['mail']: str
+    
+    If this values are Ok.
+    
+    .. note::
+        You must be careful with XX YY
+    
+    .. code-block:: python
+    
+        obj = self.pool.get('your.object')
+        somethingelse
+    
+    :returns: list -- list with ids of elements
+    '''
+    return True
+
+def search(self, cr, uid, domain, context=None):
+    '''
+    If you overwrite and orm method is important to say why you did it
+    because for the rest of community will be easier understand and create test
+    related to your change and consider in the integration with OpenERP API.
+    :context['mail']: 'new' to send a new mail or 'reply' 
+    If some option is true 
+    :return: True or other thing
+    '''
+    return True
+
+def undocummented_test_method(self, cr, uid, ids, context=None):
+    return False

=== added directory 'web_doc_oemedical/static/src/_build'