Automatically append note about version to wiki documentation

[Ryan J Ollos]

In the documentation for 0.12/, Current (1.0) and 1.1/ we add note at the top of the page. For the 1.1 documentation the note consists of the following markup:

{{{#!box note
This page documents the **1.1dev** version of Trac. See [[wiki:/TracReports]] if you need the previous version.
}}}

This page documents the 1.1dev version of Trac. See TracReports if you need the previous version.

I was thinking it would be easy to write a simple plugin implement IRequestFilter that inspected path_info and used the list of default pages to determine which pages should have the message prefixed, and then generated the message by interpolating a string template. We would want to ignore at least WikiStart, but that could be a configurable parameter.

This could be a single-file plugin, or we could make an EdgewallPlugin and extend it with other custom features in the future.

I hope to look into this after the release.

[Ryan J Ollos]

log:rjollos.git:t11725 contains a single-file plugin that adds a notice to applicable pages in the Help/Guide.

[Jun Omae]

Looks good except the following. I think we should use resource_listdir() rather than os.listdir().

contrib/help_guide_version_notice.py

@@ -13 +13 @@
 # history and logs, available at http://trac.edgewall.org/.
 
 import os
-from pkg_resources import resource_filename
+from pkg_resources import resource_listdir
 
 from trac.config import ListOption, Option
 from trac.core import Component, implements
@@ -50 +50 @@
         doc="List of pages to ignore.")
 
     def __init__(self):
-        default_pages_dir = resource_filename('trac.wiki', 'default-pages')
-        self.default_pages = os.listdir(default_pages_dir)
+        self.default_pages = resource_listdir('trac.wiki', 'default-pages')
         for page in self.ignored_pages:
             self.default_pages.remove(page)
 

[Ryan J Ollos]

Replying to jomae:

Looks good except the following. I think we should use resource_listdir() rather than os.listdir().

Thanks, I'll make that change and then commit it to /contrib. After t.e.o updates the Trac instance we can add a symlink to plugins directory, activate the plugin and then remove the existing notices from the wiki. If anyone has other ideas on how to approach this please let me know.

[Ryan J Ollos]

Single-file plugin was committed to the trunk in [13173]. I'll leave the ticket open util we have this deployed on t.e.o.

[Peter Suter]

Could this or a similar plugin maybe also warn about or highlight broken links from default to non-default pages? (Example)

[Ryan J Ollos]

Replying to psuter:

Could this or a similar plugin maybe also warn about or highlight broken links from default to non-default pages? (Example)

Yeah, that is a good idea. The single-file plugin can be renamed to help_guide_notices.py and we can add another Component to implement the functionality.

[Ryan J Ollos]

In [13213] I changed the box style to note.

TracBatchModify exhibits an issue we may want to address - checking if the page existed for the previous version of Trac before adding the notice.

[Ryan J Ollos]

Several page contain the macro invocation [[TranslatedPages]] (​th:TranslatedPagesMacro). If we could automatically append the macro output to the page we wouldn't have to filter out that content from the distributed pages.

[Ryan J Ollos]

The TicketQuery page isn't currently included in the default pages. Should we either merge it into TracQuery#UsingtheTicketQueryMacro, or add it as a new page (TracTicketQueryMacro?)?

[Ryan J Ollos]

Replying to rjollos:

Several page contain the macro invocation [[TranslatedPages]] (​th:TranslatedPagesMacro). If we could automatically append the macro output to the page we wouldn't have to filter out that content from the distributed pages.

The first few lines of content of TracGuide pages are:

= Heading
[[TracGuideToc]]
[[PageOutline]]

However, use of TracGuideToc and PageOutline is inconsistent in the TracGuide. As a side-note we might want to consistently use those two macros on every page of the TracGuide (and make a TracGuide page template).

If ​TranslatedPagesMacro is updated to version 1.0, we can take advantage of the silent parameter and append [[TranslatedPages(silent)]] after [[PageOutline]] in a IRequestFilter.post_process_request. The div will only be added to a page if translated pages exist. Once the [[Translated Pages]] line is removed from the wiki page content we won't need to do any filtering of the pages from t.e.o when pulling the changes to prepare for release.

An alternate idea would be to integrate TranslatedPagesMacro to the core, but I'll save that for later, or in the event the above plan doesn't work.

[Ryan J Ollos]

Replying to rjollos:

However, use of TracGuideToc and PageOutline is inconsistent in the TracGuide.

It would be useful to put the page outline above the TOC. However, the page outline is only needed when the page is of sufficient length and has a sufficient number of headings to make the addition of outline navigation useful.

The proposed changes are demonstrated in TracFineGrainedPermissions and TracAdmin. The page gets a bit crowded on the right side so maybe there are more extensive design changes we could make in the future. For now I'm just aiming to make the pages consistent.

[Ryan J Ollos]

Replying to psuter:

Could this or a similar plugin maybe also warn about or highlight broken links from default to non-default pages? (Example)

checkwiki.py​ appears to be looking for invalid links, but seems to report a lot of false positives​. The command line documentation says it's currently broken​.

[Jun Omae]

I wrote another checker, checkwiki-v2.py​. It tries to highlight broken links, e.g. wiki, ticket, changeset, etc….

[Ryan J Ollos]

Looks nice. Regarding the wiki edits, we should probably remove the instances of trac:WebAdmin, since most or all of those are referring to the functionality under /admin, whereas the page is referring to the plugin that is deprecated with Trac 0.11.

[Jun Omae]

Proposed changes can be found in [88da19ef/jomae.git] (jomae.git@t11725_checkwiki).

[Ryan J Ollos]

Replying to rjollos:

If ​TranslatedPagesMacro is updated to version 1.0, we can take advantage of the silent parameter and append [[TranslatedPages(silent)]] after [[PageOutline]] in a IRequestFilter.post_process_request. The div will only be added to a page if translated pages exist. Once the [[Translated Pages]] line is removed from the wiki page content we won't need to do any filtering of the pages from t.e.o when pulling the changes to prepare for release.

An alternate idea would be to integrate TranslatedPagesMacro to the core, but I'll save that for later, or in the event the above plan doesn't work.

Another idea is to have checkwiki.py remove the lines with [[TranslatedPages]].

[Ryan J Ollos]

Looks good. It is a very nice tool. A few notes:

• We should skip downloading the SandBox page from t.e.o.
• I don't think it is significant, but the PEP-0008 checker would prefer that __lines be defined in the initializer:

  contrib/checkwiki.py

  @@ -33 +33 @@
       def __init__(self, env, context, name):
           Formatter.__init__(self, env, context)
           self.__name = name
  +        self.__lines = None
   
       def handle_match(self, fullmatch):
           rv = Formatter.handle_match(self, fullmatch)

• With the exception of the missing links on WikiPageNames, all of the flagged links are within wiki code blocks. I don't have a good understanding of how the Formatter class works. Is it practical to skip those?

[Ryan J Ollos]

Replying to rjollos:

TracBatchModify exhibits an issue we may want to address - checking if the page existed for the previous version of Trac before adding the notice.

Proposed changes in log:rjollos.git:t11725-show-notice-check-existence.

[Jun Omae]

• With the exception of the missing links on WikiPageNames, all of the flagged links are within wiki code blocks. I don't have a good understanding of how the Formatter class works. Is it practical to skip those?

Okay. Fixed it in [a4876e7c/jomae.git]. Wrong line number is shown for the same lines in a wiki pages. e.g. line 16 and 26 in WikiPageNames.

[Ryan J Ollos]

It is working well. One minor change to account for possibility that the page wasn't modified:

$ PYTHONPATH= ../py2.7/bin/python contrib/checkwiki.py 
Traceback (most recent call last):
  File "contrib/checkwiki.py", line 154, in <module>
    main()
  File "contrib/checkwiki.py", line 142, in main
    wiki.save('trac', '')
  File "/home/user/Workspace/t11944/teo-rjollos.git/trac/wiki/model.py", line 138, in save
    raise TracError(_("Page not modified"))
trac.core.TracError: Page not modified

contrib/checkwiki.py

@@ -15 +15 @@
 import sys
 from pkg_resources import resource_listdir, resource_string
 
+from trac.core import TracError
 from trac.loader import load_components
 from trac.test import EnvironmentStub, Mock, MockPerm
 from trac.util.text import printout
@@ -139 +140 @@
             wiki = WikiPage(env, name)
             wiki.text = resource_string('trac.wiki', 'default-pages/' +
                                         name).decode('utf-8')
-            wiki.save('trac', '')
+            try:
+                wiki.save('trac', '')
+            except TracError:  # Page not modified
+                pass
 
     req = Mock(href=Href('/'), abs_href=Href('http://localhost/'),
                perm=MockPerm())

[Ryan J Ollos]

Replying to rjollos:

It is working well. One minor change to account for possibility that the page wasn't modified:

False alarm. This patch probably isn't necessary. I had an unversioned empty file sitting in trac/wiki/default-pages from earlier testing associated with the changes in comment:19.

[Jun Omae]

Replying to rjollos:

False alarm. This patch probably isn't necessary. I had an unversioned empty file sitting in trac/wiki/default-pages from earlier testing associated with the changes in comment:19.

Show warnings for such empty pages and skip in [0492d4d67/jomae.git].

[Ryan J Ollos]

Changes from comment:19 committed to trunk in [13698]. The latest version of the plugin has been deployed on t.e.o.

Latest changes in comment:23 look good to me.

[Jun Omae]

New checkwiki.py has been committed in [13704-13706].

[Ryan J Ollos]

Replying to rjollos:

The TicketQuery page isn't currently included in the default pages. Should we either merge it into TracQuery#UsingtheTicketQueryMacro, or add it as a new page (TracTicketQueryMacro?)?

Change will be made in #11914.

[Ryan J Ollos]

Minor additional modification to checkwiki.py in [13716:13717].

The sync is very easy now!

[Ryan J Ollos]

Replying to rjollos:

Regarding the wiki edits, we should probably remove the instances of trac:WebAdmin, since most or all of those are referring to the functionality under /admin, whereas the page is referring to the plugin that is deprecated with Trac 0.11.

I made some edits in:

• TracAdmin@52
• 0.12/TracFaq@340
• TracOnFedoraCore@85
• TracPermissions@98

However, I'm reconsidering. Maybe it would be better to edit the page named TracWebAdmin, documenting the web administration interface, and replace WebAdmin with TracWebAdmin throughout the documentation. The content on WebAdmin could be deleted and replaced with a redirect to TracWebAdmin. Pages that intend to refer to the old WebAdmin plugin such as the ChangeLog could link to an old revision of the WebAdmin page.

[Ryan J Ollos]

Replying to rjollos:

The content on WebAdmin could be deleted and replaced with a redirect to TracWebAdmin. Pages that intend to refer to the old WebAdmin plugin such as the ChangeLog could link to an old revision of the WebAdmin page.

Done in WebAdmin@54. Task will be continued in comment:14:ticket:11914.

[Ryan J Ollos]

[14463] modified help_guide_version_notice.py to exclude the SandBox page.