.. 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 ` 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*