Natural Docs
About
About Natural DocsFeaturesLanguage SupportOutput FormatsDownloadDevelopment
Make a Donation
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.  The supported formats are HTML and FramedHTML.

-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.  The default styles are Default, Small, and Roman.

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.

-hl [opt]
--highlight [opt]

Sets the syntax highlighting option used in the output.  Off turns off all syntax highlighting.  Code applies it to prototypes and (start code) segmentsAll applies it to prototypes, (start code) segments, and lines prefixed with >, |, or :.  The default is Code.

-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.

-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.

-cs [charset]
--charset [charset]
--character-set [charset]

This used to set the character set property of the generated HTML.  Natural Docs now always uses UTF-8.

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-2011 Greg Valure