<html><head><title>Running Natural Docs</title><link rel=stylesheet type="text/css" href="styles.css"><style type="text/css"><!--
.OptionTable { margin: 1em 3ex 0 3ex }
.OptionTable td { padding-bottom: 1em }
.Option { font: 10pt Courier New, Courier, monospace; color: #808080; white-space: nowrap }
.Description { padding-left: 4ex }
.Description ul { margin: 0 0 0 5ex; padding: 0 }
.ParameterGroup {
font: bold 10pt Verdana, sans-serif;
padding-top: 1em;
}
.ParameterGroupExtra {
font: italic 8pt Verdana, sans-serif;
color: #808080;
}
--></style><script language=JavaScript src="javascript/PNGHandling.js"></script><script language=JavaScript src="javascript/BrowserStyles.js"></script></head><body marginwidth=0 marginheight=0 leftmargin=0 topmargin=0><script language=JavaScript><!--
OpeningBrowserTags();// --></script>
<!-- saved from url=(0026)http://www.naturaldocs.org -->
<table width=100% border=0 cellspacing=0 cellpadding=0 class=PageTable float=center><tr><td colspan=3 class=Header><table width=100% border=0 cellspacing=0 cellpadding=0><tr><td><img src="images/header/leftside.png" width=30 height=75><a href="index.html"><img src="images/header/logo.png" width=524 height=75 alt="Natural Docs"></a></td><td align=right><img src="images/header/rightside.png" width=30 height=75></td></tr></table></td></tr><tr><td><img src="images/header/overleftmargin.png" width=10 height=6></td><td class=SideMenuTop><img src="images/header/overmenu.png" width=14 height=6></td><td class=BodyTop><img src="images/header/overbody.png" width=24 height=6></td></tr><tr><td></td><td class=SideMenu nowrap><div class=SideMenuSection><div class=SideMenuTitle><img src="images/menu/about.png" width=52 height=13 alt="About"></div><div class=SideMenuBody><a href="languages.html" class=SideMenuEntry>Language Support</a><a href="output.html" class=SideMenuEntry>Output Formats</a></div></div><div class=SideMenuSection><div class=SideMenuTitle><img src="images/menu/using.png" width=45 height=13 alt="Using"></div><div class=SideMenuBody><a href="documenting.html" class=SideMenuEntry>Documenting<br>Your Code</a><a href="keywords.html" class=SideMenuEntry>Keywords</a><span class=SideMenuEntry id=SelectedSideMenuEntry>Running</span><a href="troubleshooting.html" class=SideMenuEntry>Troubleshooting</a></div></div><div class=SideMenuSection><div class=SideMenuTitle><img src="images/menu/customizing.png" width=96 height=13 alt="Customizing"></div><div class=SideMenuBody><a href="menu.html" class=SideMenuEntry>Organizing the Menu</a><a href="styles.html" class=SideMenuEntry>CSS Styles</a><a href="customizingtopics.html" class=SideMenuEntry>Topics and Keywords</a><a href="customizinglanguages.html" class=SideMenuEntry>Languages, Indexes,<br>and Prototypes</a></div></div><div class=SideMenuSection><div class=SideMenuTitle><img src="images/menu/community.png" width=86 height=13 alt="Community"></div><div class=SideMenuBody><a href="http://www.naturaldocs.org/" class=SideMenuEntry>Web Site</a><a href="http://www.naturaldocs.org/mailinglist.html" class=SideMenuEntry>Mailing Lists</a><a href="http://www.naturaldocs.org/messageboards.html" class=SideMenuEntry>Message Boards</a><a href="http://www.naturaldocs.org/bugs.html" class=SideMenuEntry>Bugs and<br>Feature Requests</a></div></div></td><td class=Body width=100%><div class=PageTitle>Running Natural Docs</div><div class=TOC><a href="#HowAndWhen">How and When</a> · <a href="#CommandLine">Command Line</a> · <a href="#Example">Examples</a></div></div><div class=Topic><a name=HowAndWhen></a> <div class=TopicTitle>How and When</div><p>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.</p><p>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.</p><p></p></div><div class=Topic><a name=CommandLine></a><div class=TopicTitle>Command Line</div><pre>NaturalDocs -i [input (source) directory]
-o [output format] [output directory]
-p [project directory]
[options]</pre><table class=OptionTable border=0 cellspacing=0 cellpadding=0><tr><td colspan=2 class="First ParameterGroup">Required Parameters:</td></tr><tr><td class=Option>-i <i>[dir]</i><br>--input <i>[dir]</i><br>--source <i>[dir]</i></td><td class=Description><p>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. <a href="languages.html">See the list of supported programming languages.</a></p></tr><tr><td class=Option>-o <i>[fmt] [dir]</i><br>--output <i>[fmt] [dir]</i></td><td class=Description><p>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 <a href="output.html"><code>HTML</code> and <code>FramedHTML</code></a>.</p></td></tr><tr><td class=Option>-p <i>[dir]</i><br>--project <i>[dir]</i></td><td class=Description><p>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.</p></td></tr><tr><td colspan=2 class=ParameterGroup>Optional Parameters:</td></tr><tr><td class=Option>-xi <i>[dir]</i><br>--exclude-input <i>[dir]</i><br>--exclude-source <i>[dir]</i></td><td class=Description><p>Excludes a subdirectory from being scanned. The output and project directories are automatically excluded.</p></td></tr><tr><td class=Option>-img <i>[dir]</i><br>--images <i>[dir]</i></td><td class=Description><p>Adds a directory to search for image files when using <a href="documenting/reference.html#Images"><code>(see <i>[file]</i>)</code></a>.</p></td></tr><tr><td class=Option>-s <i>[style] (<i>[style]</i> ...)</i><br>--style <i>[style]</i> (<i>[style]</i> ...)</td><td class=Description><p>Selects the CSS style for HTML output. The default styles are <a href="styles.html"><code>Default</code>, <code>Small</code>, and <code>Roman</code></a>.</p><p>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.</p></td></tr><tr><td class=Option>-r<br>--rebuild</td><td class=Description><p>Rebuilds everything from scratch. All source files will be rescanned and all output files will be rebuilt</p></td></tr><tr><td class=Option>-ro<br>--rebuild-output</td><td class=Description><p>Rebuilds all output files from scratch.</p></td></tr><tr><td class=Option>-t <i>[len]</i><br>--tab-length <i>[len]</i></td><td class=Description><p>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.</p></td></tr><tr><td class=Option>-hl <i>[opt]</i><br>--highlight <i>[opt]</i></td><td class=Description><p>Sets the syntax highlighting option used in the output. <code>Off</code> turns off all syntax highlighting. <code>Code</code> applies it to prototypes and <a href="documenting/reference.html#CodeAndTextDiagrams"><code>(start code)</code> segments</a>. <code>All</code> applies it to prototypes, <code>(start code)</code> segments, and <a href="documenting/reference.html#CodeAndTextDiagrams">lines prefixed with <code>></code>, <code>|</code>, or <code>:</code></a>. The default is <code>Code</code>.</p></td></tr><tr><td class=Option>-do<br>--documented-only</td><td class=Description><p>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 <a href="languages.html">full language support</a>.</p></td></tr><tr><td class=Option>-oft<br>--only-file-titles</td><td class=Description><p>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.</p></td></tr><tr><td class=Option>-nag<br>--no-auto-group</td><td class=Description><p>Tells Natural Docs to not automatically create group topics if you don’t add them yourself.</p></td></tr><tr><td class=Option>-q<br>--quiet</td><td class=Description><p>Suppresses all non-error output.</p></td></tr><tr><td class=Option>-?<br>-h<br>--help</td><td class=Description><p>Prints the syntax reference.</p></td></tr><tr><td colspan=2 class=ParameterGroup>No Longer Supported:<div class=ParameterGroupExtra>These parameters were part of previous Natural Docs releases, but are no longer supported.</div></td></tr><tr><td class=Option>-ho<br>--headers-only</td><td class=Description><p>This used to check only the headers and not the source files in C and C++. <a href="customizinglanguages.html">Edit <code>Languages.txt</code> instead</a> and add the line <code>“Ignore Extensions: c cpp cxx”</code>.</p></td></tr><tr><td class=Option>-s Custom<br>--style Custom</td><td class=Description><p>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 <code>-s</code> instead.</p></td></tr><tr><td class=Option>-ag <i>[level]</i><br>--auto-group <i>[level]</i></td><td class=Description><p>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 <code>-nag</code> if you want to turn it off completely.</p></td></tr><tr><td class=Option>-cs <i>[charset]</i><br>--charset <i>[charset]</i><br>--character-set <i>[charset]</i></td><td class=Description><p>This used to set the character set property of the generated HTML. Natural Docs now always uses UTF-8.</p></td></tr></table></div><div class=Topic><a name=Examples></a><div class=TopicTitle>Examples</div><pre>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</pre></div></td></tr><tr><td></td><td class=SideMenuBottom><table width=100% border=0 cellspacing=0 cellpadding=0><tr><td class=SideMenuBottomLeft><img src="images/menu/bottomleft.png" width=18 height=19></td><td class=SideMenuBottomRight><img src="images/menu/bottomright.png" width=18 height=19></td></tr></table></td><td class=BodyBottom>Copyright © 2003-2010 Greg Valure</td></tr></table><script language=JavaScript><!--
ClosingBrowserTags();// --></script></body></html>
