Natural Docs
Running Natural Docs
Command Line
NaturalDocs -i [input (source) directory]
           (-i [input (source) directory] ...)
            -o [output format] [output directory]
           (-o [output format] [output directory] ...)
            -p [project directory]
            [options]

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.

-i [dir]
--input [dir]
--source [dir]
The input (source) directory.  Required.  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.  Required.  This can be specified multiple times, but only once per directory.  Natural Docs will place all generated output for each format in its directory.  Currently Natural Docs supports the following formats:
  • HTML
  • FramedHTML
-p [dir]
--project [dir]
The project directory.  Required.  Natural Docs needs to store some project data, such as where each symbol is located and when each file was last modified, so it will put that data in this directory.  Each source directory you use Natural Docs with needs its own project directory.
-s [style]
--style [style]
Selects the CSS style for HTML output.  Currently Natural Docs comes with the following styles:
  • Default
  • Small
  • Roman
  • Custom*
However, you can use any CSS file in Natural Docs’ styles directory.  Just use its name without the .css extension.  Using a value of “Custom” means that the CSS file in the output directory is specific to that project, and Natural Docs will not sync or alter it in any way.
-r
--rebuild
Rebuilds all output and data files from scratch.  It will not reset the menu.
-ro
--rebuildoutput
Rebuilds all output files from scratch.  You should use this whenever you add or change output formats.
-do
--documentedonly
Prevents undocumented code aspects from appearing in the output.  This option is only relevant if you have full language support.
-ho
--headersonly
For C and C++, check only the headers and not the source files.
-t [len]
--tablength [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.
-q
--quiet
Suppresses all non-error output.
-?
-h
--help
Prints the syntax reference.
Examples
NaturalDocs -i C:\My Project\Source
            -o FramedHTML C:\My Project\Docs
            -p C:\My Project\Natural Docs

NaturalDocs -i /src/project
            -o HTML /doc/project
            -p /etc/naturaldocs/project
            -s Small -q
Using Natural Docs

First, you obviously need to document your code in Natural Doc’s syntax.  Note that unless you have full language support, Natural Docs will only document what you explicitly document.

Second, it’s recommended that you determine the command line you need and save it as a shortcut, batch file, or script since you should be running it often and rarely fiddling with the parameters.  Make sure your output and project directories exist.

Okay, you’re all set up.  Now what?  Run it.  That’s it.  Run it periodically.  Maybe run it automatically as part of the build process.  Maybe run it automatically at certain points in the day.  But all you need to do is run it.

It will set itself up on the first run.  It will find all the source files in the input directories by itself.  It will detect when they change.  It will detect when new ones are added and old ones are deleted.  It will detect when a change in one file makes the links in another file need updating, and then it will update them.  And it will do it all with a true differential build process that only updates what needs to be updated.

Painless, huh?  That was one of Natural Docs’ goals, which was to make the program as automated as possible.  There are no project files to manage or keep in sync with your source files.  Natural Docs will just handle everything.

The only other thing you may want to do is organize the menu once in a while.  It’s not required; Natural Docs will create, organize, and maintain its own menu file.  However, you have the option to touch it up manually if you ever feel the automatic version isn’t good enough.