Integrate help pages into plugin

[Ryan J Ollos]

The help pages should be integrated into the plugin and installed with the plugin.

[EmeCas]

Replying to Ryan J Ollos:

The help pages should be integrated into the plugin and installed with the plugin. The help pages should be linked from the repository to the TracHoursPlugin project wiki page.

Can you please provide links as example about what you meant exactly, as well as a reference to a plugin that's integrating/installing the help pages in that way.

Thanks

[Ryan J Ollos]

WorkLogPlugin might be a good example of adding help. See WorkLogSetupParticipant​.

Regarding help links, I haven't looked at the plugin in a while but suggest confirming that it has standard help links at the bottom of each page, like the following example from the ticket page:

      <div id="help" i18n:msg="">
        <strong>Note:</strong> See
        <a href="${href.wiki('TracTickets')}">TracTickets</a> for help on using
        tickets.
      </div>

[EmeCas]

Replying to Ryan J Ollos:

May you please have a look at the [16658] (changeset) & [16660] (changeset).

It's incorporating a very simple user manual version, including the upgrading of installation process, as well as link in all compatible html templates as indicated with its unit testing.

Thanks

[Ryan J Ollos]

Be careful with indentation in r16660. It's easy to check and fix before committing:

$ pip install reindent
$ reindent -r -n .

[Ryan J Ollos]

​wiki:TracDev/DatabaseApi#Trac1.0API has some coding style suggestions when using the database transaction context managers. Here's an example refactoring:

trachours/setup.py

@@ -105 +105 @@
                       user_manual_content, '', 0,))
 
     def version(self):
-        with self.env.db_transaction as db:
-            cursor = db.cursor()
-            cursor.execute("""
-            SELECT value FROM system WHERE name = 'trachours.db_version'
-            """)
-            version = cursor.fetchone()
-        if version:
-            return int(version[0])
-        return 0
+        for value, in self.env.db_query("""
+                SELECT value FROM system WHERE name = 'trachours.db_version'
+                """):
+            return value
+        else:
+            return 0
 
     def create_db(self):
         ticket_time_table = Table('ticket_time', key='id')[

However, for that specific case, since you are targeting Trac >= 1.2, you can use the new database API methods, one of which is:

version = DatabaseManager(self.env).get_version(name='trachours.db_version')

See example in ​wiki:TracDev/PluginDevelopment/ExtensionPoints/trac.env.IEnvironmentSetupParticipant.

[Ryan J Ollos]

One more suggestion, a change that I've been meaning to make for some time: it was a questionable choice to name a module setup.py since that has a conventional meaning in Python. I would rename trachours/setup.py to something like trachours/db.py. You'll need to make a change to entry_points in the "real" (top-level) setup.py.

I'm unsure if you are aware in bumping version number, but builds are still being tagged with dev due to configuration in setup.cfg. No problem if that's what you want.

[EmeCas]

Replying to Ryan J Ollos:

Be careful with indentation in r16660. It's easy to check and fix before committing:

$ pip install reindent
$ reindent -r -n .

Thanks for this feedback. That's fixed. Curiously the correspondences between the changes by reindent and Pycharm inspection are different, I'm wondering if that is because some configuration.

[EmeCas]

Replying to Ryan J Ollos:

​wiki:TracDev/DatabaseApi#Trac1.0API has some coding style suggestions when using the database transaction context managers. Here's an example refactoring:

trachours/setup.py

@@ -105 +105 @@
                       user_manual_content, '', 0,))
 
     def version(self):
-        with self.env.db_transaction as db:
-            cursor = db.cursor()
-            cursor.execute("""
-            SELECT value FROM system WHERE name = 'trachours.db_version'
-            """)
-            version = cursor.fetchone()
-        if version:
-            return int(version[0])
-        return 0
+        for value, in self.env.db_query("""
+                SELECT value FROM system WHERE name = 'trachours.db_version'
+                """):
+            return value
+        else:
+            return 0
 
     def create_db(self):
         ticket_time_table = Table('ticket_time', key='id')[

However, for that specific case, since you are targeting Trac >= 1.2, you can use the new database API methods, one of which is:

version = DatabaseManager(self.env).get_version(name='trachours.db_version')

Actually. I want to maintain compatibility at least for Trac >= 1.0 , so I'll follow the previous example of refactoring.

See example in ​wiki:TracDev/PluginDevelopment/ExtensionPoints/trac.env.IEnvironmentSetupParticipant.

[Ryan J Ollos]

Replying to EmeCas:

Actually. I want to maintain compatibility at least for Trac >= 1.0 , so I'll follow the previous example of refactoring.

Another option for using those methods with Trac 1.0, you could copy the file: codereviewerplugin/1.0/coderev/compat.py​.

[EmeCas]

Replying to Ryan J Ollos:

One more suggestion, a change that I've been meaning to make for some time: it was a questionable choice to name a module setup.py since that has a conventional meaning in Python. I would rename trachours/setup.py to something like trachours/db.py. You'll need to make a change to entry_points in the "real" (top-level) setup.py.

I need to evaluate the change to see if that has any other implication, need to do anything else or maybe this is really trivial, and of course I will fix that. I think I'll create another ticket to be aware of this. See #13210

I'm unsure if you are aware in bumping version number, but builds are still being tagged with dev due to configuration in setup.cfg. No problem if that's what you want.

Yes, I'm aware of that, thanks. It's something I wanted to ask about, I would like keep DEV meanwhile until everything is stable and I can complete the basic functionality that is not completed yet. In other words, let's say at least until I can close all the tickets for those I'm the owner currently. what do you think?

[Ryan J Ollos]

Replying to EmeCas:

Yes, I'm aware of that, thanks. It's something I wanted to ask about, I would like keep DEV meanwhile until everything is stable and I can complete the basic functionality that is not completed yet. In other words, let's say at least until I can close all the tickets for those I'm the owner currently. what do you think?

Sounds good to me. Maybe bump from 0.7.xdev to 0.8.0 when you have a stable version to release.

[Ryan J Ollos]

In 16795:

TracHours 0.7.1dev: Restore Trac 1.0 compatibility

Fix coding style issues.

Refs #8277.

[EmeCas]

A simple manual had been incorporated!