Opened 12 years ago

Last modified 7 years ago

#2601 enhancement new

Improve plugin documentation

Reported by: aknuds-1 Owned by:
Priority: normal Milestone:
Component: core Keywords: plugin documentation
Cc: arvenk@…, Thijs Triemstra, Jean-Paul Calderone, jesstess, khorn, Ying Li Branch:
Author:

Description

I think the current instructions for installing Twisted plugins are rather poor, especially for someone not already knowing what to look for. That is; the Twisted application plugin howto, which I followed when writing my first plugin, mentions only that _for development purposes_ you may place your plugin in a directory called "twisted" beneath the project directory (given that the project directory is on sys.path). When figuring out how to install my plugin permanently it wasn't immediately clear to me that the general mechanism is in fact for twistd to look for "twisted" directories containing plugins along sys.path.

I found out eventually that there was a full definition of Twisted's plugin detection in the Twisted Plugin System reference, but instructions were buried in information on how to extend a plugin-based application.

So what do I suggest? Describe the general mechanism for installing plugins in the Twisted Application Plugin howto, not just the quick development fix, and make installation instructions explicit (not buried in other information) in the plugin system reference.

Change History (10)

comment:1 Changed 12 years ago by Glyph

I think that the real problem here is that the sections in the Twisted Plugin System document are wonky. There is a "Plugin Caching" section which dives into the minutæ of an implementation detail, but there is no section which specfically spells out the rules for plugin locations, or the technique that Twisted uses to make its own plugin system search all of sys.path. There is an underlying system here, twisted.python.modules, which bears some explaining of its own.

Your other suggestion I disagree with strongly, though. The "writing a twisted application plugin" document already says, in the prerequisites section, that you should have read the "twisted plugin system" document. Maybe we need to make that text blink or spin around to stress its importance or something, but we shouldn't embed it, or any of the other prerequisites (a full Python tutorial, for example) in the middle of the twistd plugin docs. The purpose of that document is to explain a specific plugin interface for a specific purpose.

comment:2 Changed 12 years ago by aknuds-1

I would contend that my other suggestion makes sense -- the TAP howto _already_ touches on how to expose your plugin, but elects to inform only of how to do this in the development case, instead of letting the reader know that this is in fact an aspect of the general plugin detection mechanism. Add to this the fact that the installation instructions are well buried in the general plugin reference, and you have a recipe for confusion IMO. I suspect the optimal solution would be to refer to the section on plugin installation instructions (assuming this is written) from the TAP howto, where it now only describes the development case.

comment:3 Changed 10 years ago by Glyph

Owner: changed from Glyph to Thijs Triemstra

comment:4 Changed 10 years ago by Thijs Triemstra

Cc: Thijs Triemstra added

Ok, what are we gonna do with this ticket?

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

Cc: Jean-Paul Calderone added

I think we can afford to have a link to the installation docs (ie plugin.xhtml) in the tap docs (ie tap.xhtml). Maybe we can even move the development-focused docs out of the tap docs and into the plugin docs.

comment:6 Changed 10 years ago by Thijs Triemstra

Cc: jesstess khorn added

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

Replying to exarkun:

I think we can afford to have a link to the installation docs (ie plugin.xhtml) in the tap docs (ie tap.xhtml).

This link is present in the trunk version of tap.xhtml.

comment:8 Changed 9 years ago by Thijs Triemstra

Cc: Ying Li added

comment:9 Changed 9 years ago by <automation>

Owner: Thijs Triemstra deleted

comment:10 Changed 7 years ago by Tom Prince

(In [37463]) Merge sslendpoint-certificateoptions-6286: Use twisted.internet.ssl.CertificateOptions in strports.

Author: hynek Reviewers: rwall, tom.prince, exarkun Fixes: #6286 Refs: #2601, #6377

twisted.internet.endpoints._parseSSL is the function used to parse string syntax for SSL endpoints. It creates a DefaultOpenSSLContextFactory. A more useful thing to do would be to create a twisted.internet.ssl.CertificateOptions instance, since that is going to be where we concentrate future development (e.g. #2061).

Note: See TracTickets for help on using tickets.