Remove //Since// version information from TracIni documentation

[Ryan J Ollos]

Discussed on the mailing list in ​gmessage:trac-dev:c136Ptgl_WU/FeZNjNkR06YJ, the Since x.y version information will be removed for Trac < 0.12.

[Ryan J Ollos]

Proposed changes in log:rjollos.git:t11824.

[Steffen Hoffmann]

Did you miss the ("enabled" added in 0.11), or was it intentional to keep just that one in trac/config.py? Other changes look right. Thanks for taking care to clean this up.

[Ryan J Ollos]

Replying to shoffmann:

Did you miss the ("enabled" added in 0.11), or was it intentional to keep just that one in trac/config.py? Other changes look right. Thanks for taking care to clean this up.

Yeah, I wasn't consistent in changing the API documentation. I was wondering whether the same approach should be taken, removing mentions of Trac < 0.12, or if the Trac 0.11 documentation might still be useful for plugin developers.

We should probably just remove mention of Trac < 0.12 from the API documentation too, but I'll just save all changes to the API documentation for another ticket and take a consistent approach when making the changes.

[Ryan J Ollos]

Committed to trunk in [13304].

I was using the PEP-0008 ​docstring conventions, putting the trailing """ on a separate line for multiline strings.

However, cleandoc doesn't strip the trailing whitespace for cases like this: trunk/trac/search/web_ui.py@:50#L39​

#: trac/search/web_ui.py:48
msgid ""
"Minimum length of query string allowed when performing a search.\n"
"        "
msgstr ""

I propose a fix for this in log:rjollos.git:t11824.1.

[Christian Boos]

Replying to rjollos:

I propose a fix for this in log:rjollos.git:t11824.1.

Be careful, cleandoc_ is a keyword for message extraction (see setup.cfg), so using it for things like cleandoc_(m) is wrong (not sure if it triggers an error, but it doesn't feel right).

[Ryan J Ollos]

Replying to cboos:

Be careful, cleandoc_ is a keyword for message extraction (see setup.cfg), so using it for things like cleandoc_(m) is wrong (not sure if it triggers an error, but it doesn't feel right).

Thanks, I guess I was unlucky enough that it didn't blow up! I've reworked the changes in log:rjollos.git:t11824.2.

[Ryan J Ollos]

Changes from comment:6 committed in [13311]. New extraction in [13312]. I did some testing by modifying po files, however I'm sure I don't have as good of an eye towards potential problems as translators do. Please let me know if you spot any issues.

[Jun Omae]

Replying to rjollos:

Changes from comment:6 committed in [13311]. New extraction in [13312]. I did some testing by modifying po files, however I'm sure I don't have as good of an eye towards potential problems as translators do. Please let me know if you spot any issues.

Why is cleandoc added to trac/util/__init__.py at [13311#file2], for backward compatibility?

trac/config.py

@@ -20 +20 @@
 from genshi.builder import tag
 from trac.admin import AdminCommandError, IAdminCommandProvider
 from trac.core import *
-from trac.util import AtomicFile, as_bool, cleandoc
+from trac.util import AtomicFile, as_bool
 from trac.util.compat import wait_for_file_mtime_change
 from trac.util.text import printout, to_unicode, CRLF
-from trac.util.translation import _, N_, tag_
+from trac.util.translation import _, N_, cleandoc, tag_
 
 __all__ = ['Configuration', 'ConfigSection', 'Option', 'BoolOption',
            'IntOption', 'FloatOption', 'ListOption', 'ChoiceOption',

trac/dist.py

@@ -71 +71 @@
         `cleandoc_keywords` option: a list of keywords to clean up the
         extracted messages with `cleandoc`.
         """
-        from trac.util import cleandoc
+        from trac.util.translation import cleandoc
 
         funcname = lineno = message_lineno = None
         kwargs_maps = func_kwargs_map = None

trac/util/__init__.py

@@ -1213 +1213 @@
                               get_date_format_hint, \
                               get_datetime_format_hint, http_date, \
                               parse_date
-from trac.util.translation import cleandoc
 
 __no_apidoc__ = 'compat presentation translation'

[Jun Omae]

Replying to jomae:

Why is cleandoc added to trac/util/__init__.py at [13311#file2], for backward compatibility?

Reconsidering,

• trac.util.text is better location for cleandoc, rather than trac.util
• Or, put implementation of cleandoc on trac.util and trac.util.translation use from trac.util import cleandoc.

[Ryan J Ollos]

I encountered what look like circular import effects when trying to put the cleandoc definition of cleandoc in trac.util or trac.util.text.

When locating in trac.util.text, the following error results:

Python: /home/user/Workspace/t11944/py2.7/bin/python
Traceback (most recent call last):
  File "contrib/make_status.py", line 7, in <module>
    from trac.util.text import print_table, printout
  File "/home/user/Workspace/t11944/teo-rjollos.git/trac/util/__init__.py", line 36, in <module>
    from trac.util.compat import any, md5, sha1, sorted
  File "/home/user/Workspace/t11944/teo-rjollos.git/trac/util/compat.py", line 24, in <module>
    from trac.util.text import cleandoc
  File "/home/user/Workspace/t11944/teo-rjollos.git/trac/util/text.py", line 30, in <module>
    from trac.util.translation import _
  File "/home/user/Workspace/t11944/teo-rjollos.git/trac/util/translation.py", line 22, in <module>
    from trac.util.text import cleandoc
ImportError: cannot import name cleandoc
make: *** [status] Error 1

We can work around that by moving the import of _ in trac.util.text. See log:rjollos.git:t11824.3.

[Jun Omae]

Replying to rjollos:

I encountered what look like circular import effects when trying to put the cleandoc definition of cleandoc in trac.util or trac.util.text. […] We can work around that by moving the import of _ in trac.util.text. See log:rjollos.git:t11824.3.

Oh, I missed circular references. Your changes look to me. Thanks!

[Ryan J Ollos]

Thanks for review. Committed in [13327].

[Ryan J Ollos]

Replying to rjollos:

Replying to shoffmann:

Did you miss the ("enabled" added in 0.11), or was it intentional to keep just that one in trac/config.py? Other changes look right. Thanks for taking care to clean this up.

Yeah, I wasn't consistent in changing the API documentation. I was wondering whether the same approach should be taken, removing mentions of Trac < 0.12, or if the Trac 0.11 documentation might still be useful for plugin developers.

We should probably just remove mention of Trac < 0.12 from the API documentation too, but I'll just save all changes to the API documentation for another ticket and take a consistent approach when making the changes.

TODO for cleaning up API documentation added to TracDev/ApiChanges/1.1.3@12.