Opened 10 years ago

Closed 9 years ago

#3246 task closed fixed (fixed)

remove all mentions of plugins.tml from the documentation

Reported by: radix Owned by:
Priority: normal Milestone:
Component: core Keywords: documentation
Cc: Thijs Triemstra Branch: branches/remove-plugins-tml-3246-2
branch-diff, diff-cov, branch-cov, buildbot
Author: thijs, exarkun

Description

There are a couple mentions in The Tutorial, and one in the TwistedQuotes document:

./howto/quotes.xhtml:    <li><a href="listings/TwistedQuotes/plugins.tml" class="py-listing">plugins.tml</a>.</li>
./howto/tutorial/configuration.xhtml:<a href="listings/finger/finger/plugins.tml" class="py-listing">finger/plugins.tml</a>
./howto/tutorial/listings/finger/finger/plugins.tml:#finger/plugins.tml

Change History (22)

comment:1 Changed 10 years ago by radix

There's also a few in the lore documentation.

comment:2 Changed 9 years ago by collab

Cc: collab added
Keywords: documentation added

comment:3 Changed 9 years ago by collab

Owner: changed from Glyph to collab
Status: newassigned

comment:4 Changed 9 years ago by Thijs Triemstra

Cc: Thijs Triemstra added; collab removed
Owner: changed from collab to Thijs Triemstra
Status: assignednew

comment:5 Changed 9 years ago by Thijs Triemstra

author: thijs
Branch: branches/remove-plugins-tml-3246

(In [24528]) Branching to 'remove-plugins-tml-3246'

comment:6 Changed 9 years ago by Thijs Triemstra

Status: newassigned

I assume the task here is to rewrite the .tml examples/documentation and convert them to the new plugin system as described on this page.

comment:7 Changed 9 years ago by Thijs Triemstra

Keywords: review added
Owner: Thijs Triemstra deleted
Status: assignednew

I'm not very familiar with the plugins system in Twisted but read the docs and attempted to move the TwistedQuotes app to the twisted.plugin.IPlugin approach. The TwistedQuotes page doesn't describe how to actually run the sample without the use of mktap, if I understand correctly, so if someone can let me know if I'm 1) on the right path with the plugin approach in r24530 and 2) what the preferred approach of running a plugin with twistd/.tac's is.

comment:8 Changed 9 years ago by radix

Keywords: review removed
Owner: set to Thijs Triemstra

Ok, so I don't think that TwistedQuotes should have plugins at all. None of the documents that refer to it actually talk about plugins (except for a misuse in design.xhtml, which refers to TwistedQuotes itself as a "plugin" but should instead use the word "package"). For example, none of the documents actually explain what that 'plugins.tml' file was doing in the TwistedQuotes package; they were probably removed a while ago.

I think we already have a good enough example of plugins in the plugins document itself, and including plugins support in TwistedQuotes is likely to just confuse readers.

So I think you should just get rid of the plugins.tml file, get rid of the reference to it in quotes.xhtml, and update design.xhtml to refer to TwistedQuotes as a "package" instead of a "plugin".

Sorry for the long review period, thijs.

comment:9 in reply to:  8 Changed 9 years ago by Thijs Triemstra

Keywords: review added
Owner: Thijs Triemstra deleted

Replying to radix:

So I think you should just get rid of the plugins.tml file, get rid of the reference to it in quotes.xhtml, and update design.xhtml to refer to TwistedQuotes as a "package" instead of a "plugin".

Made the suggested changes in r24620, putting it up for review.

comment:10 Changed 9 years ago by Jean-Paul Calderone

Keywords: review removed
Owner: set to Thijs Triemstra
  1. doc/core/howto/listings/TwistedQuotes/quoteproto.py only has whitespace changes, and they look like they change the code to not conform to the coding standard.
  2. Ditto for doc/core/howto/listings/TwistedQuotes/quoters.py
  3. There are some more mentions of plugins.tml:
    • doc/lore/howto/extend-lore.xhtml
    • doc/lore/howto/listings/lore/plugins.tml
    • doc/core/howto/tutorial/configuration.xhtml
    • doc/core/howto/tutorial/listings/finger/finger/plugins.tml

Let me know if you'd still like an answer to the questions you asked in your comment prior to radix's review.

comment:11 in reply to:  10 Changed 9 years ago by Thijs Triemstra

Keywords: review added
Owner: Thijs Triemstra deleted

Replying to exarkun:

  1. doc/core/howto/listings/TwistedQuotes/quoteproto.py only has whitespace changes, and they look like they change the code to not conform to the coding standard.
  2. Ditto for doc/core/howto/listings/TwistedQuotes/quoters.py

Right, reverted that change in r24641

  1. There are some more mentions of plugins.tml:
    • doc/lore/howto/extend-lore.xhtml
    • doc/lore/howto/listings/lore/plugins.tml

I can't just rip this lore example out without influencing the rest of the howto, or..? What to do with this?

  • doc/core/howto/tutorial/configuration.xhtml
  • doc/core/howto/tutorial/listings/finger/finger/plugins.tml

Should this tml/mktap stuff be replaced by a .tac?

comment:12 Changed 9 years ago by Jean-Paul Calderone

Keywords: review removed
Owner: set to Thijs Triemstra

I can't just rip this lore example out without influencing the rest of the howto, or..? What to do with this?

Lore supports new-style plugins too, so I think the change we need to make is to convert the .tml file to a new-style plugin and update the prose which talks about it to agree. Hopefully a lot of text will be obsolete or can be replaced with a reference to the plugin howto.

Should this tml/mktap stuff be replaced by a .tac?

A twistd plugin probably makes more sense and is a smaller change. All mktap plugins are twistd plugins by default. So this would become like "twistd finger ..." instead of "mktap finger ...; twistd -f finger.tap".

comment:13 Changed 9 years ago by Jean-Paul Calderone

(In [25643]) replace the old-style lore plugin with a new-style lore plugin and update the documentation

refs #3246

comment:14 Changed 9 years ago by Jean-Paul Calderone

(In [25644]) replace the old-style finger plugin with a new-style twistd plugin and update the documentation

refs #3246

comment:15 Changed 9 years ago by Jean-Paul Calderone

(In [25645]) stop talking about TwistedQuotes entirely

The plugin stuff is all irrelevant to this pb document. The features relevant to pb explained by TwistedQuotes are already explained in other parts of this document.

refs #3246

comment:16 Changed 9 years ago by Jean-Paul Calderone

(In [25646]) get rid of another TwistedQuotes tml file

refs #3246

comment:17 Changed 9 years ago by Jean-Paul Calderone

Author: thijsthijs, exarkun
Branch: branches/remove-plugins-tml-3246branches/remove-plugins-tml-3246-2

(In [25647]) Branching to 'remove-plugins-tml-3246-2'

comment:18 Changed 9 years ago by Jean-Paul Calderone

Keywords: review added
Owner: Thijs Triemstra deleted

Fixed the remaining issues, I think. Please review.

comment:19 Changed 9 years ago by Thijs Triemstra

Keywords: review removed
Owner: set to Jean-Paul Calderone

Looks good to me, not sure why you're commenting out some stuff in extend-lore.xhtml though?

comment:20 Changed 9 years ago by Jean-Paul Calderone

I commented out the stuff in lore because it wasn't providing any value to readers. It might be useful to a future lore maintainer as a hint about what documentation still needs to be written, though.

comment:21 Changed 9 years ago by Jean-Paul Calderone

Resolution: fixed
Status: newclosed

(In [25672]) Merge remove-plugins-tml-3246-2

Author: thijs, exarkun, itamarst Reviewer: radix, thijs Fixes: #3246

Remove from the documentation all remaining references to the old style of plugins and replace them with documentation based on the new style of plugins, where appropriate. The Lore plugin interface IProcess is also slightly improved so that it at least defines the attributes which are actually required of it and does not document an attribute which is never used by Lore.

comment:22 Changed 7 years ago by <automation>

Owner: Jean-Paul Calderone deleted
Note: See TracTickets for help on using tickets.