From 279aa412e31ce6bb325241468b03ec411c267dc0 Mon Sep 17 00:00:00 2001 From: carol15022 Date: Tue, 3 Mar 2015 11:38:57 -0300 Subject: [PATCH] Documentation of Trac Data API. --- colab/proxy/trac/data_api.py | 183 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ docs/source/conf.py | 4 +++- docs/source/dev.rst | 2 +- docs/source/index.rst | 3 ++- docs/source/plugindev.rst | 2 +- docs/source/trac.rst | 13 +++++++++++++ docs/source/user.rst | 68 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 7 files changed, 271 insertions(+), 4 deletions(-) create mode 100644 docs/source/trac.rst diff --git a/colab/proxy/trac/data_api.py b/colab/proxy/trac/data_api.py index d23a041..b2ebfb0 100644 --- a/colab/proxy/trac/data_api.py +++ b/colab/proxy/trac/data_api.py @@ -1,3 +1,4 @@ +# -*- coding: utf-8 -*- from re import match from django.db import connections @@ -9,6 +10,10 @@ from colab.proxy.utils.proxy_data_api import ProxyDataAPI class TracDataAPI(ProxyDataAPI): def fetch_data(self): + """ This is the pricipal method whose function is just make the call the + other methods. + + """ connection = connections['trac'] cursor = connection.cursor() self.fetch_data_wiki(cursor) @@ -17,6 +22,17 @@ class TracDataAPI(ProxyDataAPI): self.fetch_data_revision(cursor) def fetch_data_attachment(self, empty_cursor): + """ This method is responsible for seeking the attachment data in +        trac database and transfer them to the colab database. + + :param empty_cursor: A cursor coming from connectinos, it is necessary +         import the connections library from django.db, with it we can run +         sql commands. + +        :returns: Return is an attachment object with your saved data +         in the colab database. + + """ attachment = Attachment() cursor = self.attachment_cursor(empty_cursor) attachment_dict = self.dictfetchall(cursor) @@ -38,6 +54,17 @@ class TracDataAPI(ProxyDataAPI): attachment.save() def fetch_data_revision(self, empty_cursor): + """ This method is responsible for seeking the revision data in +        trac database and transfer them to the colab database. + +        :param empty_cursor: A cursor coming from connectinos, it is necessary +       import the connections library from django.db, with it we can run +         sql commands. + +        :returns: Return is an revision object with your saved data +         in the colab database. + + """ revision = Revision() cursor = self.revision_cursor(empty_cursor) revision_dict = self.dictfetchall(cursor) @@ -52,6 +79,17 @@ class TracDataAPI(ProxyDataAPI): revision.repository_name = repository_dict[line['repos']] def fetch_data_ticket(self, empty_cursor): + """ This method is responsible for seeking the ticket data in +        trac database and transfer them to the colab database. + +        :param empty_cursor: A cursor coming from connectinos, it is necessary +         import the connections library from django.db, with it we can run +         sql commands. + +        :returns: Return is an ticker object with your saved data +         in the colab database. + + """ ticket = Ticket() collaborators = [] cursor = self.ticket_cursor(empty_cursor) @@ -80,6 +118,17 @@ class TracDataAPI(ProxyDataAPI): ticket.collaborators = collaborators def fetch_data_wiki(self, empty_cursor): + """ This method is responsible for seeking the wiki data in +        trac database and transfer them to the colab database. + +        :param empty_cursor: A cursor coming from connectinos, it is necessary +         import the connections library from django.db, with it we can run +         sql commands. + +        :returns: Return is an wiki object with your saved data +         in the colab database. + + """ wiki = Wiki() cursor = self.wiki_cursor(empty_cursor) wiki_dict = self.dictfetchall(cursor) @@ -98,6 +147,19 @@ class TracDataAPI(ProxyDataAPI): wiki.save() def dictfetchall(self, cursor): + """ This method is responsible for taking the cursor content +        and turn it into a dictionary. + +        The cursor returns an array of tuples, With this method it will return + a list of dictionaries.. + +        :param cursor: A cursor coming from connections, it is necessary +         import the connections from library django.db, with it we can run +         sql commands. + +        :returns: Return are cursor.fetchall() in the format of dictionary + + """ desc = cursor.description return [ dict(zip([col[0] for col in desc], row)) @@ -105,26 +167,88 @@ class TracDataAPI(ProxyDataAPI): ] def wiki_cursor(self, cursor): + """ This is the method in charge of getting the wiki table data and +        put them in the cursor. + +        :param cursor: A cursor coming from connections, it is necessary +         import the connections from library django.db, with it we can run +         sql commands. + +        :returns: The return is the result of the desired query + + """ cursor.execute('''SELECT * FROM wiki;''') return cursor def attachment_cursor(self, cursor): + """ This is the method in charge of getting the attachment table data and +        put them in the cursor. + +        :param cursor: A cursor coming from connections, it is necessary +         import the connections from library django.db, with it we can run +         sql commands. + +        :returns: The return is the result of the desired query + + """ cursor.execute('''SELECT * FROM attachment;''') return cursor def ticket_cursor(self, cursor): + """ This is the method in charge of getting the ticket table data and +        put them in the cursor. + +        :param cursor: A cursor coming from connections, it is necessary +         import the connections from library django.db, with it we can run +         sql commands. + +        :returns: The return is the result of the desired query + + """ cursor.execute('''SELECT * FROM ticket;''') return cursor def revision_cursor(self, cursor): + """ This is the method in charge of getting the revision table data and +        put them in the cursor. + +        :param cursor: A cursor coming from connections, it is necessary +         import the connections from library django.db, with it we can run +         sql commands. + +        :returns: The return is the result of the desired query + + """ cursor.execute('''SELECT * FROM revision;''') return cursor def repository_cursor(self, cursor): + """ This is the method in charge of getting the repository table data and +        put them in the cursor. + +        :param cursor: A cursor coming from connections, it is necessary +         import the connections from library django.db, with it we can run +         sql commands. + +        :returns: The return is the result of the desired query + + """ cursor.execute('''SELECT * FROM repository;''') return cursor def get_wiki_modified(self, cursor, wiki_name): + """ This is the method in charge of getting the datetime in the wiki was +        modified and put it in GMT format. + +        :param cursor: A cursor coming from connections, it is necessary +         import the connections from library django.db, with it we can run +         sql commands. + +        :param wiki_name: is the name of the current wiki. + +        :returns: The return is the result of the desired query + + """ cursor.execute("""SELECT TIMESTAMP WITH TIME ZONE 'epoch' + \ (MAX(wiki.time)/1000000) * INTERVAL '1s', \ name from wiki where(name=\'""" + wiki_name + """\') \ @@ -134,6 +258,18 @@ class TracDataAPI(ProxyDataAPI): return modified_data def get_wiki_created(self, cursor, wiki_name): + """ This is the method in charge of getting the datetime in the wiki was +        created and put it in GMT format. + +        :param cursor: A cursor coming from connections, it is necessary +         import the connections from library django.db, with it we can run +         sql commands. + +        :param wiki_name: is the name of the current wiki. + +        :returns: The return is the result of the desired query + + """ cursor.execute("""SELECT TIMESTAMP WITH TIME ZONE 'epoch' + \ (MIN(wiki.time)/1000000) * INTERVAL '1s', \ name from wiki where(name=\'""" + wiki_name + """\') \ @@ -143,6 +279,18 @@ class TracDataAPI(ProxyDataAPI): return modified_data def get_attachment_created(self, cursor, attachment_id): + """ This is the method in charge of getting the datetime in the + attachment was created and put it in GMT format. + +        :param cursor: A cursor coming from connections, it is necessary +         import the connections from library django.db, with it we can run +         sql commands. + +        :param attachment_id: is the id of the current attachment. + +        :returns: The return is the result of the desired query + + """ cursor.execute("""SELECT TIMESTAMP WITH TIME ZONE 'epoch' + \ (MIN(attachment.time)/1000000) * INTERVAL '1s', \ id from attachment \ @@ -153,6 +301,18 @@ class TracDataAPI(ProxyDataAPI): return modified_data def get_revision_created(self, cursor, revision): + """ This is the method in charge of getting the datetime in the revision + was modified and put it in GMT format. + +        :param cursor: A cursor coming from connections, it is necessary +         import the connections from library django.db, with it we can run +         sql commands. + +        :param revision: is the current revision. + +        :returns: The return is the result of the desired query + + """ cursor.execute("""SELECT TIMESTAMP WITH TIME ZONE 'epoch' + \ (MIN(revision.time)/1000000) * INTERVAL '1s', \ rev from revision where(rev=\'""" + revision + """\') \ @@ -162,6 +322,18 @@ class TracDataAPI(ProxyDataAPI): return modified_data def get_ticket_created(self, cursor, ticket_id): + """ This is the method in charge of getting the datetime in the ticket + was created and put it in GMT format. + +        :param cursor: A cursor coming from connections, it is necessary +         import the connections from library django.db, with it we can run +         sql commands. + +        :param ticket_id: is the id of the current ticket. + +        :returns: The return is the result of the desired query + + """ cursor.execute("""SELECT TIMESTAMP WITH TIME ZONE 'epoch' + \ (MIN(ticket.time)/1000000) * INTERVAL '1s', \ id from ticket where(id=""" + str(ticket_id) + """) \ @@ -171,6 +343,17 @@ class TracDataAPI(ProxyDataAPI): return modified_data def get_ticket_modified(self, cursor, ticket_id): + """ This is the method in charge of getting the datetime in the ticket + was modified and put it in GMT format. + +        :param cursor: A cursor coming from connections, it is necessary +         import the connections from library django.db, with it we can run +         sql commands. + +        :param ticket_id: is the id of the current ticket. + +        :returns: The return is the result of the desired query + """ cursor.execute("""SELECT TIMESTAMP WITH TIME ZONE 'epoch' + \ (MAX(ticket.time)/1000000) * INTERVAL '1s', \ id from ticket where(id=""" + str(ticket_id) + """) \ diff --git a/docs/source/conf.py b/docs/source/conf.py index 7d6f63f..6a6da29 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -18,7 +18,9 @@ import os # If extensions (or modules to document with autodoc) are in another directory, # 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('.')) +sys.path.insert(0, os.path.abspath('../../colab/proxy')) +from django.conf import settings +settings.configure() # -- General configuration ------------------------------------------------ diff --git a/docs/source/dev.rst b/docs/source/dev.rst index 51bfcc7..f0dfd6e 100644 --- a/docs/source/dev.rst +++ b/docs/source/dev.rst @@ -1,5 +1,5 @@ Developer Documentation -================== +======================= Getting Started --------------- diff --git a/docs/source/index.rst b/docs/source/index.rst index a95f72b..23508aa 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -30,6 +30,8 @@ Contents: user plugindev dev + trac + Indices and tables @@ -38,4 +40,3 @@ Indices and tables * :ref:`genindex` * :ref:`modindex` * :ref:`search` - diff --git a/docs/source/plugindev.rst b/docs/source/plugindev.rst index 2f6eb0d..5054ff6 100644 --- a/docs/source/plugindev.rst +++ b/docs/source/plugindev.rst @@ -1,5 +1,5 @@ Plugin Developer Documentation -================== +============================== Getting Started --------------- diff --git a/docs/source/trac.rst b/docs/source/trac.rst new file mode 100644 index 0000000..b524a45 --- /dev/null +++ b/docs/source/trac.rst @@ -0,0 +1,13 @@ +trac package +============ + +Submodules +---------- + +trac.data_api module +-------------------- + +.. automodule:: trac.data_api + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/source/user.rst b/docs/source/user.rst index 4a8a6f4..8df449a 100644 --- a/docs/source/user.rst +++ b/docs/source/user.rst @@ -16,6 +16,74 @@ Plugins ------- .. TODO +Trac +++++ + + +Dado que o Trac ja está instalado : + +- Vocẽ pode instalá-lo facilmente da seguinte maneira: + +.. code-block:: sh + + $ pip install trac + +Para ativar o plugin do Trac deve-se primeiramente configurar o banco de dados +do trac em: + +1. vim /etc/colab/settings.yml + + +.. code-block:: yaml + + DATABASES: + default: + ENGINE: django.db.backends.postgresql_psycopg2 + HOST: localhost + NAME: colab + USER: colab + PASSWORD: colab + trac: + ENGINE: django.db.backends.postgresql_psycopg2 + HOST: localhost + NAME: trac + USER: colab + PASSWORD: colab + +2. Ainda no mesmo arquivo descomentar o Trac em PROXIED_APPS + +.. code-block:: yaml + + PROXIED_APPS: + # gitlab: + # upstream: 'http://localhost:8090/gitlab/' + # private_token: '' + trac: + upstream: 'http://localhost:5000/trac/' + +3. Criar o banco de dados no postgresql com usuário colab + +.. code-block:: sh + + $ sudo -u postgres psql + $ create database trac owner colab; + +4. Agora você deve gerar as migrações do trac + +.. code-block:: sh + + # Dado que você está na pasta do colab + $ workon colab + $ colab-admin makemigrations trac + $ colab-admin migrate + +5. Por fim basta importar os dados do trac ( pode levar algumtempo ). + +.. code-block:: sh + + # Dado que você está na pasta do colab + $ colab-admin import_proxy_data + Settings -------- -- libgit2 0.21.2