Configuring the Documentation
KDevelop contains a very powerful documentation facility which provides access to several kinds of extensive documentation. In e.g. IDEAl mode you find a Documentation tab at the right border of the work area.
The KDevelop documentation window (IDEAl mode)
KDevelop must have loaded the Documentation plugin in order to view the documentation tree. See the Plugin Tools section for more info.
You may set up contents and behaviour of the various parts of this documentation window if you select -> from the menubar. The Customize KDevelop dialog will pop up, where you have to select Documentation in the left hand window.
The thus displayed configuration page shows three tabbed configuration dialog pages, namely:
| Documentation Collections |
| Full Text Search |
| Other |
The documentation configuration settings have been divided into a series of documentation collections, each providing access to documentation files of some unique format and content type. These setups control which documentation items will be listed on the Contents page of the KDevelop Documentation facility, and how the user may access documentation details by indexed and full text searches.
The Documentation tab provides a series of configuration pages which are ordered vertically like a stack of index cards. One page at a time will open after a click on its index card title:
| Qt™ Documentation Collection |
| CHM Documentation Collection |
| Doxygen Documentation Collection |
| KDevelop TOC Documentation Collection |
| Devhelp Documentation Collection |
| Custom Documentation Collection |
Setting up documentation collections
All configurations pages on the Documentation tab use a common layout. You will find the currently available documentation items of this type listed on the open page to the left and a set of buttons to the right.
There are three buttons available to maintain the contents of the documentation setup pages:
Opens a Documentation Catalog Properties dialog as shown below where you can select the source location of the documentation item to be added and name it.
Opens a Documentation Catalog Properties dialog as shown below where you can change the source location of the documentation item previously selected in the list and rename it.
Removes the selected documentation entry from the list.
The entry will be removed from the list only. Actual documentation sources remain untouched. You will have to remove them explicitely by other means.
Add or change a documentation item
The button to the right of the Location field opens a directory dialog whose entries usually will be filtered according to the file type of the selected configuration page.
The Title field may not be accessible, depending on the documentation type to be maintained.
Every documentation setup page shows the listed documentation items in a table with four columns:
If this check box is marked, this documentation item will show up on the Contents page of the KDevelop Documentation facility.
Unchecking the TOC check box will in turn disable the Index and Search check boxes (see below). Thus you cannot have documentation collection items indexed but not shown in the contents.
If this check box is marked, an internal index will be built of this documentation item. This provides fast access to the documentation by the use of the Index and (optionally) Finder pages of the KDevelop Documentation facility.
The internal index will be built the first time the user selects the Index page. This will delay the first access noticeably, because the index will be read from disk and then cached.
All subsequent indexed searches will however use this chache and thus work significally faster.
If this check box is marked, the contents of this documentation item will be included in the full text search path of the Search page of the KDevelop Documentation facility.
KDevelop utilizes the htdig application collection to perform full text searches. This search is done over an internal index, the htdig machinery has to build before it can be used.
Any change of the Search check box marks will thus effect the search runs only after you rebuilt the index on the Search page of the KDevelop Documentation facility.
This is the name of the Documentation item as it will be shown on the Contents page of the KDevelop Documentation facility.
Former KDevelop versions allowed to select the documentation items to be displayed on a per-project basis. This is not available any more.
On this configuration page all Qt™ documentation is set up.
Setting up the Qt™ documentation collection
Normally KDevelop will fill this in on its first start-up. It looks for standard *.xml, or *.dcf documentation files in the Qt™ installation directory. The table to the left lists the files KDevelop found by their standard titles.
If you have a non-standard installation, either there will be no information listed at all or the entries will possibly refer to improper locations (e.g. to another Qt™ installation available in your system). You may adjust the entries using the buttons to the right of the list field.
KDevelop will use the titles already provided by the installed Qt™ documentation. Hence the Title field in the Documentation Catalog Properties dialog is inaccessible.
By default, not all Qt™ documentation will be shown on the Contents page of the KDevelop Documentation facility. Use the TOC check box in the setup table to select the documentation to be shown.
If you want to have some specific Qt™ documentation included in the search indexes or full text search use the Index and Searchcheck boxes in the setup table.
On this configuration page you may collect documentation according to the Microsoft® CHM help file standard.
Setting up Microsoft® CHM standard documentation files
By default, this configuration page will be empty (as shown above). You may add new entries using the buttons to the right of the list field. KDevelop will filter *.chm files in the directory dialog associated to the and buttons.
For more information on the format of Microsoft® *.chm files see e.g. PHP: Documentation - Extended CHM Format at http://de2.php.net/docs-echm.php.
On this configuration page all API documentation generated by Doxygen is set up.
Setting up Doxygen generated API documentation
In short, such an API documents the interface to certain library functions. The API documentation on this page should be produced by the externally provided Doxygen tool.
Doxygen generated API documentationconsists of a series of html files, starting with index.html. Additionally there may exist tag files which contain information to link to already existing API documentations. Thus KDevelop will look for index.html and *.tag files when seaching for Doxygen generated API documentation.
There are some structural constraints assumed when searching for Doxygen generated API documentation. The directory in which the index.html file resides should contain subdirectories with separate documentation collections. Each of these subdirectories is assumed to contain a .tag file and a html/ subdirectory.
You may have a look at $ for an example of such a Doxygen API documentation layout.
KDEDIR/share/doc/HTML/en/kdelibs-apidocs
The older KDE KDoc generated API format is not directly supported any more. If you still want to use such documentation, you may add it on the Custom Documentation Collection page.
KDevelop will have filled in a link to the current KDE Libraries API, provided it found one. There are several ways for KDevelop to find out:
Either you provided the configure command with the
--with-kdelibsdoxy-dir option when you compiled
KDevelop (see the How to Obtain a KDevelop API Documentation chapter).
Or the configure command did automatically find a Doxygen generated KDE Libraries API in one of several standard locations it knows of.
Or as a last resort the $ was found at the first KDevelop startup.
KDEDIR/share/doc/HTML/en/kdelibs-apidocs/
If KDevelop did not find a valid Doxygen generated KDE Libraries API at its first start-up the Doxygen Documentation Collection list will be empty.
You may add your own API documentation entries (e.g. from your current projects) by using the buttons to the right. If you want to have them included in the indexed and/or full text search mark the Index or Search check boxes in the setup table.
KDevelop uses the title information from the index.html. Hence the Title field in the Documentation Catalog Properties dialog is inaccessible.
The KDE system provides more API documentation than the KDE Libraries API only. You will need additional interfaces information if you want to e.g. include the Kate part into you programs. For this Kate part API for example you should compile and install the KDE Base Libraries API from the sources (using the make apidox and make install commands on the kdebase sources) and then add an entry to the Doxygen Documentation Collection list like this:
Adding a KDE Base API to the list
(Of course you should replace the /home/dev/mykde-system/ directory in the Location field example with the path to your KDE installation.)
You must put the API of your current project into this Doxygen Documentation Collection as well. Former KDevelop versions did put it into the documentation tree on a per-project basis. This is not provided any more.
The main bulk of the KDevelop documentation facility provides immediate access to structured documentation, local as well as remote ones. You can configure this on the KDevelopTOC Documentation Collection page.
Providing KDevelopTOC structured documentation access
KDevelop comes with a bunch of predefined KDevelopTOC files which are automatically entered in the table at installation time. To keep the display manageable only the most often used will initially be marked for display. If you want to see another documentation, mark the TOC check box in the setup table.
KDevelopTOC files cannot be indexed to perform a full text search because they usually point to a remote location. On the other hand, such a .toc file can have an index manually defined, using the <index> tag. Thus the Index check box will be enabled ony when KDevelop finds an <index> tag in the .toc file. (For more detail see the description below in the KDevelop TOC Files section.)
The Search check box in the setup table will alway be disabled.
You may add new entries using the buttons to the right of the list field. KDevelop will filter *.toc files in the directory dialog associated to the and buttons.
Other than former KDevelop versions will the button not change the *.toc files on disk, so the remove operation is safe now.
There is a special feature associated with this. To illustrate, follow these steps: In the documentation tree find an entry shortly below the Qt™/KDE documentation (e.g. “KDE2 Development Book (kde.org)”). Click on the plus sign next to it. A tree will open where you can quickly navigate to subsequent chapters nested several levels deep, all offline. But if you finally select one of the chapters, KDevelop will in many cases try to access a remote documentation file.
The rationale behind this is not only to locally navigate remote documentation without wasting net access ressources, but to provide the developer with easy, structured access to the documentation he/she needs. Using these tools one can access almost any local or remote documentation in a structured fashion even if the original is laid out flat or structured in another way. All that is needed is access to files and/or parts of files which are displayable by the Konqueror.
Such structured access is made possible through the use of special “table of content” files, which are denoted by .toc filename extensions. Any such KDevelop TOC file contains an XML™ structured description of the document to be accessed.
When KDevelop was installed usually a series of predefined .toc files has been put into the $KDEDIR/share/apps/kdevdocumentation/tocs directory. These are fairly simple, structured text files. You may look at them using a text editor or other text display facility.
Basic Structure of KDevelop TOC Files
<!DOCTYPE kdeveloptoc>
|
<kdeveloptoc>
|
| (title) |
| (base address) |
| (content structure) |
| (index structure) |
</kdeveloptoc>
|
This XML™ structure will be parsed by the KDevelop Documentation plugin to set up the documentation tree contents and to guide the user in navigating the documentation. It contains all information necessary to display titles and access the documentation file contents.
<title>
(some title string)
</title>
|
This is the title KDevelop will display at the basic levels in the documentation tree.
This displayed title cannot be changed by the user. If you want another text be displayed, you must manually change the <title> entry in the .toc file.
<base href="
(base document URL)
"/>
|
This URL points to the location where all files of this documentation are located. It will be prepended before each section URL in the following content structure list. So, if you e.g. downloaded a documentation from a remote server, all you need to display the files from this new location is to change its <base> URL.
<tocsect1 name="
(section title)
" url="
(section URL)
">
|
| ... |
<tocsectn name="
(section title)
" url="
(section URL)
"/>
|
| ... |
</tocsect1>
|
All remaining navigation and access information is stored in a series of nested <tocsecti> ... </tocsecti> pairs. Each i denotes a consecutive nesting level down to number n which will correspond to the finally displayed documentation section.
Any <tocsecti> entry must have a name="xxx" attribute associated with it (the "xxx" denotes the actual title string). This name will be displayed as level title in the documentation tree. It should correspond to an actual documentation section.
There may be an url="" attribute associated with any i nesting level. When the user clicks on a section title in the documentation tree KDevelop will try to access the file at the location pointed to by the combined base and section URL.
The <tocsectn/> entry must have an url="" attribute whatsoever.
This final nested <tocsectn/> does not come in pairs but will immediately be closed by a / before the > bracket.
Any address combined of base and section URL must point to some displayable text file. Usually this will be an HTML-structured file. It is possible to link to anchor marks within such an HTML file using the standard # notation of the format: /base-url/section-url#anchor-mark.
<index>
|
<entry name="
(index entry title)
" url="
(index section URL)
"/>
|
</index>
|
Index is a plain list of index entries - pairs of title and URL. Index is not mandatory.
DevHelp documentation is another means of structured documentation access. It uses structured table of content files denoted by a .devhelp extension similar to KDevelop TOC files to access documentation for the GNOME 2 desktop.
You can control which DevHelp files should be accessible on the DevHelp Documentation Collection configuration page.
Providing DevHelp documentation
DevHelp files originally were accessible on the LiDN website, but this seems to be not maintained for some time now. More recent DevHelp documentation is available at the DevHelp Books Download web page.
When KDevelop is installed it will attempt to find all .devhelp files in some standard places in the system, e.g. in the subdirectories of /opt/gnome/share/. Initially these files will not be marked for display. If you want to see another documentation, mark the TOC check box in the setup table.
You may add new entries using the buttons to the right of the list field. KDevelop will filter *.toc files in the directory dialog associated to the and buttons.
This is for your own purpose. You may add almost any documentation files here, provided they can be displayed by the Konqueror plugins.
Providing custom documentation
Usually this collection will be empty at first KDevelop startup. We have filled in a deliberate item to show the entry structure.
Handling is straightforward here. Use the buttons to the right of the list field to add, edit or remove the document items. KDevelop will not filter anything in the directory dialog associated to the and buttons.
You will have to explicitely select the items for display in the KDevelop documentation facility. Mark the TOC check box of the entry in the setup table.
Custom documention cannot be indexed or searched. Thus the Index and Search check boxes have no effect here as shown above.
