doc/developer-guide/documentation/plugins.en.rst

.. Licensed to the Apache Software Foundation (ASF) under one
   or more contributor license agreements.  See the NOTICE file
   distributed with this work for additional information
   regarding copyright ownership.  The ASF licenses this file
   to you under the Apache License, Version 2.0 (the
   "License"); you may not use this file except in compliance
   with the License.  You may obtain a copy of the License at

   http://www.apache.org/licenses/LICENSE-2.0

   Unless required by applicable law or agreed to in writing,
   software distributed under the License is distributed on an
   "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
   KIND, either express or implied.  See the License for the
   specific language governing permissions and limitations
   under the License.

.. include:: ../../common.defs

.. _developer-doc-plugins:

Documenting Plugins
*******************

Plugins can provide tremendously useful functionality for users of |TS|, but it
does them little good if there are no instructions on how to use the plugins
properly. In the interest of encouraging useful documentation on all the
features available to those deploying |TS| in their infrastructure, this
section lays out a series of guidelines and offers a basic template for adding
new entries to the :ref:`admin-plugins` chapter of the :ref:`admin-guide`.

Structure
=========

Ideally, every plugin will provide documentation covering the following general
topics (preferably in top-level sections named to match):

Introduction
------------

A brief section in which the plugin's core functionality is explained in a
quickly digestible paragraph or two. For the sake of brevity, this section
should omit discussion of configuration details in favor of providing a more
10,000 foot view of the plugin features.

Purpose
-------

Why would someone want to use this particular plugin? What problems does it
solve, or what features not attainable otherwise (through core functionality or
other plugins) does it provide to an administrator or user? While not exactly a
product pitch, this is the section in which the case for using the plugin at
all should be made.

Dependencies
------------

If the plugin has external dependencies, they should be listed in full, with
the exception of items already required by a bare-bones |TS| build. If the
plugin has no unusual or non-standard dependencies, this section may be safely
omitted.

For example, there is no need to list a C++ compiler as a requirement, but if
the plugin requires OpenCL and a specific brand of GPU expansion card to
perform some wacky image transformations on cached objects - that really should
be disclosed.

If any of the dependencies are optional, that should be noted as well as the
functionality that may be missing should the dependency not be present.

Installation
------------

Detailed instructions on how to install the plugin if it is not built by
default with |TS| or requires any additional libraries, services, or
applications outside of |TS| to be present.

If the plugin is marked stable and included by default in |TS| builds, then it
may not be necessary to include any installation steps beyond noting that it is
part of the default |TS|.

Configuration
-------------

Detailed instructions on how and where to provide configuration data for the
plugin's features. It is important to use |RST| references for all mentions of
|TS| configuration variables, as well as their containing configuration files.

If configurations are generated by scripts included with the plugin source
code, those scripts should be mentioned and their usage should be shown.

Caveats (or Limitations)
------------------------

Notes about any peculiarities with the plugin, incompatibilities or strange
behaviors when used in conjunction with other features, or special
considerations for its deployment that might affect an administrator's use of
the plugin or their infrastructure's architecture.

If the plugin contains known limitations (perhaps it only works with some
protocols, can understand only some media types, or is especially
non-performant under specific configurations) they should be noted. If
possible, workarounds for these limitations should be suggested, or if none are
available that should be noted.

Examples
--------

Every plugin should aim to have at least one, complete example of its usage
beginning with its basic installation, showing a complete (and ideally working)
configuration, as well as sample output from |TS| in which the plugin's effects
may be observed.

Further Reading
---------------

Consolidated list of references to outside materials and documents which may be
relevant to the plugin, such as RFCs and white papers. If the plugin is related
to external projects, or has been the subject of benchmarks or articles, those
may be useful to list as well.

Additional Sections
===================

Not all plugins will fit perfectly within that list of sections. Some may
require additional details, or such extended discussion that it is best to
break the plugin's documentation down a bit further. In general, it is
recommended to place these additional documentation sections in between
*Configuration* and *Caveats* or *Limitations*.

This ordering permits a quick scanning of the plugin's purpose, basic method of
installation, and initial overview of its configuration before becoming mired
down in dissertation length details of every possible configuration, warning,
and trade-off that may affect deployments.

In cases where the array of configuration possibilities is extensive, it is
recommended that the initial *Configuration* section describe the most common
configuration scenario(s), while noting that there are many other possibilities
that will be covered in the sections that follow. This, it is hoped, will get
the usual case out of the way quickly for most |TS| administrators while
limiting the paralysis of choice they may face otherwise.

Documentation Template
======================

For the convenience of plugin developers, this manual includes a
:ref:`plugin documentation template <developer-doc-plugin-template>` which you
may use as a base. The template includes placeholders, with markup, for common
features of the documentation which may be relevant for your plugin. Developers
are very strongly encouraged to use this template whenever possible, as a means
of producing and maintaining a consistent format for plugin documentation.


.. _developer-doc-plugin-template:

.. note:: *to be done*