On Thu, Aug 15, 2013 at 1:41 PM, Terry Brown <[email protected]>wrote:
> I'm not that familiar with Leo's docs. stack, but I'm wondering where > the canonical version of plugin docs should be, and vote for the doc > string of the plugin. > I agree completely. Leo already uses the docstring in the plugins menu, and the docstring is, by far, the most natural place for complete documentation. This thread was intended to ensure that a) all docstrings are up to date and b) any additional discussions (archived in LeoDocs.leo) are reflected in the docstrings. In other words, I hope that the (temporary!) archives in LeoDocs.leo would jog the memory of plugin writers. > > .../leo/doc/plugin_catalog.py can then pull them all together. There > are over 100 plugins, so this must be something that should be > automated / data driven rather than manual document maintenance driven. > Thanks for this. I'll put running this script in the distribution checklist, with additional notes to myself in LeoDocs.leo. Even copy / pasting from the plugin doc strings to the main docs seems > like a violation of the DRY principle. > > The part that would have to be in the main docs because it doesn't fit > in individual plugins would be some overview of plugins, like... > > There's all sorts of functionality in plugins, some of them are major > add-ons / capabilities, like valuespace, richtext, printing, todo, > etc. and some are long forgotten experiments which probably don't > work anymore. > > Then maybe a list of a few categories of activity, like writing > documents, writing code, PIM, utilities, and a terse list of the major > actively maintained plugins in each category. With links from these > lists to the docs for plugin as collected by plugin_catalog.py, with, > finally, a comment that it's worth reading through the list at the top > of plugin_catalog.py's output to find other plugins in different levels > of functionality for more specific tasks. > > Even the terse list, above, could be automatically generated if the > TODO: parts of plugin_catalog.py can be done, namely: > > - Design encoding of plugin status in rst docstring > > - interface (qt/tk/both) > - maintained / working / old / broken > - maintainer > > - List of commands provided by plugin (or command pattern, e.g > active-path-\*) > - List of semantic tags provided by plugin (@bookmark...) > > (last two are less important / not needed initially) > > That said, I will look at the documentation you've rescued from the > emails, but with an eye to incorporating it into the docstrings of the > plugins. That avoids the problem of collaboration in a .leo file, > because the collaboration is just in the editing of the plugins .py > files. > Thanks. It's a big and mostly thankless job. Your to-do items are interesting. For example, at present the plugin description in release notes are just copies of the full description, but I'll edit them down to very short summaries with links to the docs. This too might be automated. Edward -- You received this message because you are subscribed to the Google Groups "leo-editor" group. To unsubscribe from this group and stop receiving emails from it, send an email to [email protected]. To post to this group, send email to [email protected]. Visit this group at http://groups.google.com/group/leo-editor. For more options, visit https://groups.google.com/groups/opt_out.
