Topics.txt · Topic Types vs. Keywords · Adding Topic Types
Changing Keywords · Altering Behavior · Syntax Reference
Natural Docs has two files called
You should edit the one in your project directory whenever possible. It keeps your changes separate and easier to manage, plus you don’t have to reapply them whenever you upgrade. Editing the one in Natural Docs’ Config directory would be better only if you’re using Natural Docs with a lot of projects and would like the changes to apply everywhere.
Topic Types vs. Keywords
It’s important to understand the difference between topic types and keywords. Topic types have their own indexes and behavior settings. You’ll reference them by name when dealing with indexes in the menu file or prototype detection in the language file, but not when documenting your code unless you make their names keywords as well.
You use keywords when documenting your code. There can be many keywords per topic type, and they are completely interchangable.
Suppose you document a class with the
Adding Topic Types
If you want to be able to document something in Natural Docs doesn’t handle by default, you want to create your own topic type for it. Let’s say you’re working on a video game and you want to document all the sound effects because you want to keep track of what each one is for and have an index of them. You’d add this to your topics file:
Topic Type: Sound Effect Plural: Sound Effects Keywords: sound sound effect
Sound effects can now be documented with the
Here are a couple of other things you may want to add:
Topic Type: Sound Effect Plural: Sound Effects Scope: Always Global Keywords: sound, sounds sound effect, sound effects
You can set the scope behavior of the topic type. Your options are:
Here we set it to
The other thing we did was add plural keywords, which you do by using a comma after an existing keyword. These keywords are used for list topics so we don’t have to document each one individually with the full syntax.
There are more options, these are just the most important ones. See the full syntax reference for the rest.
If you’d like to collect prototypes for your new topic type, you have to do that by editing
Adding and Changing
If you’re defining your own topic type or editing the main topics file, you simply add to the keywords list:
Topic Type: Sound Effect Keywords: sound, sounds sound effect, sound effects
It doesn’t matter if the keyword was previously defined for a different topic type. Just define it again and the definition will change.
If you want to add keywords to one of the main topic types from the project file, use
Alter Topic Type: General Keywords: note notes
Natural Docs will keep a list of the main file’s topic types in your project file so that you can do this easily.
Sometimes a keyword just gets in the way. It’s too common in your comments and Natural Docs keeps accidentally picking them up as topics when that isn’t what you wanted. You can get rid of keywords completely by either deleting them from the main file or putting this in your project file:
Ignore Keywords: about title
If you only have a few, you can use this syntax as well:
Ignore Keywords: note, notes, title
You can change the behavior of any topic type defined in the main file via your project file. Just use
Alter Topic Type: Constant Scope: Always Global
Natural Docs will keep a list of the main file’s topic types in your project file so you can do this easily. See the syntax reference below for a full list of your options.
Ignore Keywords: [keyword], [keyword] ... [keyword] [keyword], [keyword] ...
Ignores the keywords so that they’re not recognized as Natural Docs topics anymore. Can be specified as a list on the same line and/or following like a normal Keywords section.
Topic Type: [name] Alter Topic Type: [name]
Creates a new topic type or alters an existing one. The name can only contain letters, numbers, spaces, and these characters:
There are a number of default types that must be defined in the main file, but they will be listed there since it may change between versions. The default types can have their keywords or behaviors changed, though, either by editing the default file or by overriding them in the user file.
Specifies the plural name of the topic type. Defaults to the singular name. Has the same restrictions as the topic type name.
Whether the topic type gets an index. Defaults to yes.
Scope: [normal|start|end|always global]
How the topic affects scope. Defaults to normal.
Class Hierarchy: [yes|no]
Whether the topic is part of the class hierarchy. Defaults to no.
Page Title if First: [yes|no]
Whether the title of this topic becomes the page title if it is the first topic in a file. Defaults to no.
Break Lists: [yes|no]
Whether list topics should be broken into individual topics in the output. Defaults to no.
Can Group With: [topic type], [topic type], ...
Lists the topic types that can be grouped with this one in the output. If two or more topic types often appear together, like Functions and Properties, this will allow them to be grouped together under one heading if it would cause too many groups otherwise.
Keywords: [keyword] [keyword], [plural keyword] ...
A list of the topic type’s keywords. Each line after the heading is the keyword and optionally its plural form. This continues until the next line in “
|Copyright © 2003-2011 Greg Valure|