[WIP] Edit feature plugin documentation

[micahellison]

This builds on the namespace-based export plugins #1006. I want to do what I can to make sure that this documentation is relatively easy and approachable for new plugin developers.

Done so far:

• use same style as the rest of the documentation (informal "you", jrnl instead of jrnl, minimize passive voice)
• remove justification for change, since this is a how-to guide
• add reference to Python namespace package docs
• use tip/warning tooltip styles
• order documentation in order from general to specific

Checklist

• I have read the contributing doc.
• I have included a link to the relevant issue number.
• I have tested this code locally.
• I have checked to ensure there aren't other open pull requests
  for the same issue.
• I have written new tests for these changes, as needed.
• All tests pass.

[micahellison]

When I started working on this, I thought it would be a good sub-section of the new Contributing section in #1180 but after actually seeing it, I realized it makes a lot more sense to keep it separate. Writing your own plugin is a lot different than contributing directly to the jrnl project, and a lot of the contributing documentation isn't even related to coding.

In the long run, I think we'll want an additional user doc on installing plugins, so we end up with two main plugin docs. I made issue #1267 for that.

[MinchinWeb]

Hey @micahellison ! Further to f228149, I really think we should keep the sample plugins as part of the displayed documentation.

1. Keeping them in means that the (generated) documentation is self-contained, which means you can turn it in to a PDF and read it offline.
2. Keeping the plugin inline reduces context changes. My hope is that the plugin documentation is expansive and comprehensive enough that you could write your plugins based on the documentation alone, without having to context-swtich to find something elsewhere on the internet.

I specifically wrote as simple a complete plugin as I could with an eye of putting these in the documentation, and they come in at 40 and 50 lines. If these are two long, maybe we should put some work on slimming them down.

Hope my couple thoughts helps.

[micahellison]

HI @MinchinWeb, funnily enough, I removed the included code because I found the context change of a page full of code really jarring. It might be appropriate for a tutorial, but I don't believe it's appropriate for a reference, except as an addendum rather than than something that interrupts the flow of an article. Splitting up the docs could help with this.

Also, I am still not feeling great about the example code. I understand your motivation for wanting to have a short-as-possible example of a plugin, but I'm far more concerned that providing an incomplete example as the bedrock for a whole plugin ecosystem may end up causing lots of difficulty for both us and the users. That's why I filed #1268, with the hopes that creating a sample plugin repo with some testing infrastructure would lead to well-tested plugins.

[micahellison]

Fixed some merge issues but tests are failing now -- looks like it's due to linting issues on the feature-plugins branch.

[stale]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.

[micahellison]

Closing due to staleness. I'll get back to this if/when the feature-plugin branch stabilizes.