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.

Remember that if you’re using Windows, you’ll need to install a copy of Perl if you haven’t already done so. You can download ActiveState’s ActivePerl for free.

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 seach this and all its subdirectories for files with Natural Docs content. It can be specified multiple times. See the list of supported programming languages.
-o [fmt] [dir] --output [fmt] [dir]	The output format and directory. This can be specified multiple times, but only once per directory. Natural Docs will place all generated output for each format in its directory. See the list of supported output formats.
-p [dir] --project [dir]	The project directory. Natural Docs needs to store some project data, such as where each topic is located and when each file was last modified, so it will put that data in this directory. Each project you document with Natural Docs needs its own separate directory.
Optional Parameters:
-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.
-s [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.
-xi [dir] --exclude-input [dir] --exclude-source [dir]	Excludes a subdirectory from being scanned. The output and project directories are automatically excluded.
-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.
-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.
-nag --no-auto-group	Tells Natural Docs to not automatically create group topics if you don’t add them yourself.
-q --quiet	Suppresses all non-error output.
-? -h --help	Prints the syntax reference.
Depreciated Parameters: These options 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.