Testing and Packaging Documentation Sets

The final steps in building a documentation set are to ensure that Xcode can correctly access, display, and search the contents of the documentation set, and to package the documentation set bundle for distribution.

This chapter describes how to use the docsetutil tool to test the functionality and contents of your documentation set’s indexes, how to test whether Xcode can access and display your documentation, and how to package your documentation set bundle as an XAR archive.

Querying and Testing Indexes

Because Xcode relies on the indexes to find and access the content of a documentation set, you should test those indexes thoroughly. The same docsetutil tool that you used to index your documentation set content also lets you test and validate the generated index files.

The following sections show how you can use the docsetutil tool to compare the contents of the indexes to the contents of the local documentation set bundle, test the search results returned by the indexes, and print out index contents.

Comparing the Contents of the Documentation Set Bundle and its Indexes

One of the simplest tests you can perform on your documentation set is to validate that the generated indexes match the content of the documentation set bundle. You can do this using the docsetutil validate command, as in this example:

> <Xcode>/usr/bin/docsetutil validate com.mycompany.MyProduct.docset

The docsetutil tool warns of any discrepancies between the files listed in the indexes and the files in the local copy of the documentation set bundle. The tool detects any nonexistent files referenced in the nodes and tokens files or files that disappeared after the indexes were built.

Verifying Indexes

Another useful feature of the docsetutil tool is the ability to print the contents of a documentation set’s indexes. By examining the contents of your documentation set’s indexes, you can verify that they contain the expected number of nodes and tokens, and that the document hierarchy that they describe is correct.

The docsetutil tool can print:

  • The total number of nodes in the documentation set

  • The node hierarchy; that is, all or part of the TOC of the documentation set

  • The total number of documents in the full-text index

  • The path to each node in the full-text index

  • The total number of tokens in the API index

  • The identifiers of each of the tokens in the API index

Use the docsetutil dump command to print the contents of your documentation set’s indexes. For example, the following command prints the contents of the test documentation set’s indexes: 

> <Xcode>/usr/bin/docsetutil dump com.mycompany.MyProduct.docset

The output generated by this command looks similar to that shown in Listing 8-1.

Listing 8-1  Dumping the contents of a documentation set’s indexes

Documentation set contains 9 nodes in hierarchy
My Doc Set
  IB
    IB Reference
  Performance
    Performance Tools Tutorial
  Xcode
    User Guide
    Tutorial
    Build Settings
 
Full text index contains 614 documents
docset://__DEFAULT__
  IBInspector_class
  XcodeBuildSettingRef
  XcodeQuickTour
  XcodeUserGuide
  InstrumentsQuickTour
count = 6
 
API index contains 9 tokens
Objective-C/instm/IBInspector/document
Objective-C/instm/IBInspector/inspectedObjects
Objective-C/instm/IBInspector/inspectedObjectsController
Objective-C/instm/IBInspector/label
Objective-C/instm/IBInspector/refresh
Objective-C/clm/IBInspector/sharedInstance
Objective-C/clm/IBInspector/supportsMultipleObjectInspection
Objective-C/instm/IBInspector/view
Objective-C/instm/IBInspector/viewNibName

Notice that docsetutil prints the node hierarchy, followed by the number of documents in the full-text index. Following that, docsetutil prints the path to each node in the full-text index. These paths are grouped according to the root where the nodes are found. The _DEFAULT_ root represents the Documents directory of the documentation set bundle. If you identified additional roots by specifying a fallback root using the -fallback option, they are listed under the _FALLBACK_ root. If you specified files to download and include using the -download option, these also appear in the output of the docsetutil dump command, along with the paths to the nodes at that location.

By default, docsetutil prints only the paths to the nodes that are explicitly specified in the Nodes.xml file. However, folder and bundle nodes typically represent multiple HTML files. You can also have docsetutil print the paths to each of the individually indexed files in a node using the -text-depth option.

The contents of the indexes for very large documentation sets can be difficult to parse. You can test smaller portions of the indexes by restricting the output of the docsetutil dump command. You do this in the following ways:

  • Use the -skip-text and -skip-api options to skip either the full-text or API indexes when printing out the index contents.

  • Use the -toc-depth option to limit the depth of the document hierarchy printed by docsetutil.

  • Use the -text-depth option to limit the amount of information printed about the documentation set’s nodes and their contents.

  • Use the -node option to dump only the contents of the specified node and its subnodes.

For example, the following command prints only the document hierarchy of the documentation set:

> <Xcode>/usr/bin/docsetutil dump com.mycompany.MyProduct.docset -skip-text -skip-api

For more on these options, see docsetutil Reference.

Querying Indexes

You can also use the docsetutil tool to test the search results returned by your documentation set’s indexes. The command docsetutil search searches for a particular string in the indexes of the specified documentation set. This command has one required option, -query, which specifies the search string. For example, the following command searches for the word “trace” in a documentation set: 

> <Xcode>/usr/bin/docsetutil search -query trace com.mycompany.MyProduct.docset

The output of the docsetutil tool looks similar to that shown in Listing 8-2. It notes the maximum rank of the matching results and lists the normalized score and path of each matching HTML page.

Listing 8-2  Sample output from docsetutil search

Max score: 90.330826
 Score   Path
 0.129 InstrumentsQuickTour/Built-InInstruments/chapter_6_section_6.html
 0.166 XcodeUserGuide/Contents/Resources/en.lproj/06_02_db_set_up_debug/chapter_40_section_10.html
...
 1.000 InstrumentsQuickTour/WorkingWithInstruments/chapter_3_section_4.html

By default, docsetutil search queries both the full-text and API indexes. However, it is often easier to query and test a single index at a time. Use the -skip-text and -skip-api flags to disable the full-text or API indexes, respectively.

For example, the following command queries a documentation set’s API index for information on the CreateWindow symbol:

> <Xcode>/usr/bin/docsetutil search com.mycompany.MyProduct.docset -query CreateWindow -skip-text

You can also limit the scope of the search to a particular node and its subnodes, using the -node option, as described in docsetutil Reference. The following command searches for the string “trace” in only those documents that are part of the Xcode node and its subnodes:

> <Xcode>/usr/bin/docsetutil search -query trace  -node Xcode com.mycompany.MyProduct.docset

Testing Display and Navigation

In addition to testing the content in the indexes, you should make sure that your documentation set displays properly in the Xcode Documentation window. To do so, simply drop the documentation set bundle into its default installation location.

After placing the documentation set bundle in its default installation location, launch Xcode, and open the Documentation preferences. (You may have to quit and restart Xcode if it was already running when you installed the documentation set bundle.) Check to make sure that that the documentation set appears in the documentation sets list. You should also check the Home pop-up menu that’s in the Documentation window toolbar (in Xcode 3.2 and later) and see whether your documentation set appears in it. When you choose your documentation set from the menu, the Documentation window should display the root node page.

Finally, in the Documentation window, perform a variety of searches to ensure that all the search types supported by your documentation set work as expected and return reasonable results.

Packaging Documentation Sets

The last thing you need to do before distributing your documentation set is to package it. Using the docsetutil package command, you can package your documentation set as an XAR archive.

For example, the following command packages a documentation set and places it on the Desktop: 

> <Xcode>/usr/bin/docsetutil package -output ~/Desktop/MyProductDocSet.xar com.mycompany.MyProduct.docset

If you do not specify an output path, docsetutil places the archive in the same folder as your documentation set bundle. You can also sign the package using the -signid option and generate (or update) an Atom feed for the documentation set using the -atom option. For more information on these options, see docsetutil Reference.



Copyright © 2009 Apple Inc. All Rights Reserved. Terms of Use | Privacy Policy | Updated: 2009-05-05