2d44b2b36d
The new sphinx version introduces some changes that break build: * Warns if code cannot be parsed for highlighting. Fix the code so that it can be parsed, this includes uncommenting "..." lines. Note that not every config file is an ini-file. Also, the parser seems to have bugs and cannot parse all files. Fix mysql ini file and enable the parameter, see http://dev.mysql.com/doc/refman/5.7/en/innodb-parameters.html#sysvar_innodb_file_per_table * :option: works only with declared options, replace useage with simple ``. This change only handles a few files, more to come later. Change-Id: I7c7335e514581622dd562ee355f62d6ae1beaa18
3.6 KiB
Proprietary driver docs
Many OpenStack projects include drivers to support specific hardware or software. Examples are:
- Cinder: block storage drivers
- Neutron: network plug-ins
- Nova: hypervisors
- Trove: different databases
The documentation team documents the following reference drivers in the Configuration Reference Guide:
- For cinder: volume drivers - document LVM and NFS, backup drivers - document swift
- For glance: document local storage, cinder, and swift as back ends
- For neutron: document ML2 plug-in with the mechanisms drivers Open vSwitch and Linux bridge
- For nova: document KVM (mostly), send Xen open source call for help
- For sahara: Apache Hadoop
- For trove: document all supported Open Source database engines like MySQL.
If a vendor wants to document their driver, they are invited - but not forced -to include their documentation in the Configuration Reference if they commit to maintain the documentation.
Important
Other documentation (including the Cloud Admin Guide and Networking Guide) will not contain content for third-party drivers. In these books, where third party drivers exist, add the statement: “For other drivers, see Chapter X in the Configuration Reference Guide”.
Guidelines
The following are guidelines for drivers documented by the OpenStack community:
- The complete solution must be open source and use standard hardware
- The driver must be part of the respective OpenStack repository
- The driver is considered one of the reference drivers
For documentation of other drivers, the following guidelines apply:
- The Configuration Reference contains a small section for each driver, see below for details.
- Only drivers are covered that are contained in the official OpenStack project repository for drivers (for example in the main project repository or the official third-party repository).
If a vendor wants to add more than the minimal documentation, they need to commit to the following guidelines:
- Assign an editor that is responsible for the content.
- Review and, if necessary, update their driver for each release cycle.
Default section format for external drivers
For each external driver, the driver is briefly documented in a way that is version independent and includes the current configuration options.
Each section should follow this format:
A short paragraph explaining the driver.
A link with detailed instructions to the vendor site (if there is one).
A default paragraph, for example:
Set the following in your ``cinder.conf``, and use the following options to configure it. volume_driver = cinder.volume.drivers.smbfs.SmbfsDriverAnd finally, the autogenerated configuration options.
Driver vendors can send in patches for these, or create bugs.
Full documentation by vendors
If a vendor wants full documentation in the Configuration Reference, they have to add to the wiki page a contact editor that will take care of the vendor driver documentation. The Documentation team will assign bugs to the contact person, include the contact person in reviews for the vendor driver, and expects timely responses.
If vendor driver documentation becomes outdated and the contact person is not reacting to requests, the Documentation team will change the full documentation to a minimal version.
The documentation team will review vendor drivers and ensure that the various driver documents follow a consistent standard.