Edgewall Software
Modify

Opened 8 years ago

Closed 8 years ago

Last modified 7 years ago

#11725 closed enhancement (fixed)

Automatically append note about version to wiki documentation

Reported by: Ryan J Ollos Owned by:
Priority: normal Milestone: not applicable
Component: project Version:
Severity: normal Keywords:
Cc: Branch:
Release Notes:
  • The help_guide_version_notice single-file plugin adds a notice to each page in the TracGuide with the status of the documentation and a link to another version of the documentation.
  • The check_wiki command line tool highlights links that aren't followable.
API Changes:
Internal Changes:

Description (last modified by 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.

Attachments (5)

checkwiki_output.txt (24.4 KB ) - added by Ryan J Ollos 8 years ago.
checkwiki-v2.py (2.9 KB ) - added by Jun Omae 8 years ago.
checkwiki-highlight-missing.png (34.7 KB ) - added by Jun Omae 8 years ago.
checkwiki-red-highlight-missing.png (18.8 KB ) - added by Jun Omae 8 years ago.
checkwiki-red-highlight-missing-20150125.png (155.6 KB ) - added by Ryan J Ollos 8 years ago.

Download all attachments as: .zip

Change History (36)

comment:1 by Ryan J Ollos, 8 years ago

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

comment:2 by Jun Omae, 8 years ago

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

  • contrib/help_guide_version_notice.py

    diff --git a/contrib/help_guide_version_notice.py b/contrib/help_guide_version_notice.py
    index ad19e0f..9e497c1 100644
    a b  
    1313# history and logs, available at http://trac.edgewall.org/.
    1414
    1515import os
    16 from pkg_resources import resource_filename
     16from pkg_resources import resource_listdir
    1717
    1818from trac.config import ListOption, Option
    1919from trac.core import Component, implements
    class HelpGuideVersionNotice(Component):  
    5050        doc="List of pages to ignore.")
    5151
    5252    def __init__(self):
    53         default_pages_dir = resource_filename('trac.wiki', 'default-pages')
    54         self.default_pages = os.listdir(default_pages_dir)
     53        self.default_pages = resource_listdir('trac.wiki', 'default-pages')
    5554        for page in self.ignored_pages:
    5655            self.default_pages.remove(page)
    5756

in reply to:  2 comment:3 by Ryan J Ollos, 8 years ago

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.

comment:4 by Ryan J Ollos, 8 years ago

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.

comment:5 by Peter Suter, 8 years ago

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

in reply to:  5 comment:6 by Ryan J Ollos, 8 years ago

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.

Last edited 8 years ago by Ryan J Ollos (previous) (diff)

comment:7 by Ryan J Ollos, 8 years ago

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.

comment:8 by Ryan J Ollos, 8 years ago

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.

Last edited 8 years ago by Ryan J Ollos (previous) (diff)

comment:9 by Ryan J Ollos, 8 years ago

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?)?

Last edited 8 years ago by Ryan J Ollos (previous) (diff)

in reply to:  8 ; comment:11 by Ryan J Ollos, 8 years ago

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.

Last edited 8 years ago by Ryan J Ollos (previous) (diff)

in reply to:  11 comment:12 by Ryan J Ollos, 8 years ago

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.

Last edited 8 years ago by Ryan J Ollos (previous) (diff)

by Ryan J Ollos, 8 years ago

Attachment: checkwiki_output.txt added

in reply to:  5 comment:13 by Ryan J Ollos, 8 years ago

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.

Last edited 8 years ago by Ryan J Ollos (previous) (diff)

by Jun Omae, 8 years ago

Attachment: checkwiki-v2.py added

by Jun Omae, 8 years ago

comment:14 by Jun Omae, 8 years ago

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

comment:15 by Ryan J Ollos, 8 years ago

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.

by Jun Omae, 8 years ago

comment:16 by Jun Omae, 8 years ago

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

in reply to:  11 comment:17 by Ryan J Ollos, 8 years ago

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]].

comment:18 by Ryan J Ollos, 8 years ago

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

      diff --git a/contrib/checkwiki.py b/contrib/checkwiki.py
      index 809278c..a5ca65b 100755
      a b class DefaultWikiChecker(Formatter):  
      3333    def __init__(self, env, context, name):
      3434        Formatter.__init__(self, env, context)
      3535        self.__name = name
       36        self.__lines = None
      3637
      3738    def handle_match(self, fullmatch):
      3839        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?

in reply to:  7 comment:19 by Ryan J Ollos, 8 years ago

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.

in reply to:  18 comment:20 by Jun Omae, 8 years ago

  • 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.

comment:21 by Ryan J Ollos, 8 years ago

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

    diff --git a/contrib/checkwiki.py b/contrib/checkwiki.py
    index 25bb52e..5f49cdb 100755
    a b  
    1515import sys
    1616from pkg_resources import resource_listdir, resource_string
    1717
     18from trac.core import TracError
    1819from trac.loader import load_components
    1920from trac.test import EnvironmentStub, Mock, MockPerm
    2021from trac.util.text import printout
    def main():  
    139140            wiki = WikiPage(env, name)
    140141            wiki.text = resource_string('trac.wiki', 'default-pages/' +
    141142                                        name).decode('utf-8')
    142             wiki.save('trac', '')
     143            try:
     144                wiki.save('trac', '')
     145            except TracError:  # Page not modified
     146                pass
    143147
    144148    req = Mock(href=Href('/'), abs_href=Href('http://localhost/'),
    145149               perm=MockPerm())

in reply to:  21 ; comment:22 by Ryan J Ollos, 8 years ago

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.

in reply to:  22 comment:23 by Jun Omae, 8 years ago

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].

comment:24 by Ryan J Ollos, 8 years ago

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.

comment:25 by Jun Omae, 8 years ago

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

comment:26 by Ryan J Ollos, 8 years ago

Description: modified (diff)

in reply to:  9 comment:27 by Ryan J Ollos, 8 years ago

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.

comment:28 by Ryan J Ollos, 8 years ago

Release Notes: modified (diff)
Resolution: fixed
Status: newclosed

comment:29 by Ryan J Ollos, 8 years ago

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

The sync is very easy now!

in reply to:  15 ; comment:30 by Ryan J Ollos, 8 years ago

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:

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.

Last edited 8 years ago by Ryan J Ollos (previous) (diff)

in reply to:  30 comment:31 by Ryan J Ollos, 8 years ago

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.

comment:32 by Ryan J Ollos, 7 years ago

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

Modify Ticket

Change Properties
Set your email in Preferences
Action
as closed The ticket will remain with no owner.
The resolution will be deleted. Next status will be 'reopened'.
to The owner will be changed from (none) to the specified user.

Add Comment


E-mail address and name can be saved in the Preferences .
 
Note: See TracTickets for help on using tickets.