Running Natural Docs

Language Support Output Formats
Documenting
Your Code Keywords Running Troubleshooting
Organizing the Menu CSS Styles Topics and Keywords Languages, Indexes,
and Prototypes
Web Site Mailing Lists Message Boards Bugs and
Feature Requests

Running Natural Docs
How and When

Probably the best way to run Natural Docs is as part of the build process. This way every time you compile your code, your documentation is updated as well and you always have a current reference. Natural Docs has a differential build process so it will not rebuild the entire set of documentation every time it’s run.

If you’d like to run it manually instead, you should determine the command line you need and save it as a shortcut, batch file, or script since you should be running it often and will rarely need to fiddle with the parameters.

Command Line

    NaturalDocs -i [input (source) directory]
                -o [output format] [output directory]
                -p [project directory]
                [options]

Required Parameters:
-i [dir] --input [dir] --source [dir] | The input (source) directory. Natural Docs will build the documentation from the files in this directory and all its subdirectories. You can specify it multiple times to include multiple directories. See the list of supported programming languages.
-o [fmt] [dir] --output [fmt] [dir] | The output format and directory. This can also be specified multiple times, so you can build the documentation in multiple formats in a single run. See the list of supported output formats.
-p [dir] --project [dir] | The project directory. Natural Docs needs a place to store configuration and data files for each project it’s run on, so this is where it will put them. No two projects should share the same directory.
Optional Parameters:
-xi [dir] --exclude-input [dir] --exclude-source [dir] | Excludes a subdirectory from being scanned. The output and project directories are automatically excluded.
-img [dir] --images [dir] | Adds a directory to search for image files when using `(see [file])`.
-s [style] ([style] ...) --style [style] ([style] ...) | Selects the CSS style for HTML output. See the default list of styles. You can use any CSS file in your project directory or Natural Docs’ Styles directory just by using its name without the .css extension. If you include more than one, they will all be included in the HTML that order.
-r --rebuild | Rebuilds everything from scratch. All source files will be rescanned and all output files will be rebuilt
-ro --rebuild-output | Rebuilds all output files from scratch.
-t [len] --tab-length [len] | Sets the number of spaces tabs should be expanded to. This only needs to be set if you use tabs in example code or text diagrams. The default is 4.
-do --documented-only | Tells Natural Docs to only include what you explicitly document in the output, and not to find undocumented classes, functions, and variables. This option is only relevant if you have full language support.
-oft --only-file-titles | Tells Natural Docs to only use the file name for its menu and page titles. It won’t try to determine one from the contents of the file.
-nag --no-auto-group | Tells Natural Docs to not automatically create group topics if you don’t add them yourself.
-cs [charset] --charset [charset] --character-set [charset] | Sets the character set property of the generated HTML, such as UTF-8 or Shift_JIS. The default leaves it unspecified.
-q --quiet | Suppresses all non-error output.
-? -h --help | Prints the syntax reference.
No Longer Supported: These parameters were part of previous Natural Docs releases, but are no longer supported.
-ho --headers-only | This used to check only the headers and not the source files in C and C++. Edit `Languages.txt` instead and add the line `“Ignore Extensions: c cpp cxx”`.
-s Custom --style Custom | This used to tell Natural Docs not to alter the CSS file in the output directory. Copy your custom CSS file to your project directory and use it with `-s` instead.
-ag [level] --auto-group [level] | This used to set the level of auto-grouping between Full, Basic, and None. The algorithm was improved so there’s no need for separate levels anymore. You can use `-nag` if you want to turn it off completely.

Examples

    NaturalDocs -i C:\My Project\Source
                -o FramedHTML C:\My Project\Docs
                -p C:\My Project\Natural Docs

    NaturalDocs -i /project/src1
                -i /project/src2
                -o HTML /project/doc
                -p /project/nd
                -s Small -t 3

Copyright © 2003-2008 Greg Valure