Getting Set Up
Download and Install

The first thing we need to do is download Natural Docs. Do that here:

Download
Instructions for Windows

Natural Docs on Windows requires .NET 3.5 or higher. If you're using Windows 7 or later you already have it.

Natural Docs is a command line (console) application so it can be integrated into development environments and build processes. That means there's no graphical interface. If you're already familiar with command line applications you can skip to Starting a New Project. Otherwise keep these instructions handy while reading later sections.

You can run Natural Docs from an icon by creating a shortcut to it. Right click on an empty part of your desktop and select New > Shortcut. In the location field type the full path to NaturalDocs.exe in quotes (for example "C:\Program Files (x86)\Natural Docs\NaturalDocs.exe") and put any parameters you need outside the quotes. You'll learn about which parameters to use later. It will look like this:

    "C:\Program Files (x86)\Natural Docs\NaturalDocs.exe" C:\My Project\ND Config --pause-before-exit

Click Next, give it a name, and click Finish. You'll now have an icon you can double-click to run Natural Docs with those parameters. If you ever need to change them you would right click on the shortcut, select Properties, and change the parameters in the Target field.

If you are running Natural Docs this way I would recommend always adding --pause-before-exit to the parameter list so the console window doesn't close automatically and you can see the status messages. Once you have everything working the way you want you can change it to --pause-on-error so it only stays open when there's a problem.

Instructions for macOS and Linux

Natural Docs requires Mono 4.0 or later to run on macOS and Linux. Download it here.

In all the examples below you're going to add "mono" before the command line and use Unix paths, so instead of:

    NaturalDocs.exe C:\My Project\ND Config

you'll use:

    mono NaturalDocs.exe /My Project/ND Config

Natural Docs is a command line (terminal) application so it can be integrated into development environments and build processes. That means there's no graphical interface. If you want to run it manually you have to do it through a terminal window.

Starting a New Project

If you've already used the old version of Natural Docs with your code, skip to Upgrading a 1.x Project.

First you need to create two folders. One of them will be for the generated documentation and the other will be for Natural Docs' configuration and working data. The latter is called your project configuration folder.

Run Natural Docs with the project configuration folder as a parameter. Just something like this:

    NaturalDocs.exe C:\My Project\ND Config

It will create three configuration files there for you to edit. We don't have to worry about Comments.txt and Languages.txt for now, we only need Project.txt. Open it up.

All the configuration files contain explanations of their options so you never have to remember them, they're right there in front of you. You'll see the Project Information section first, so add a Title line with the name of your project:

    Title: My Project

Now scroll down to the Source Code section. This is where you tell Natural Docs which folders to scan. Add them with Source Folder lines:

    Source Folder: C:\My Project\Source

You can have more than one, though if there are a lot of them you also have the option of putting the parent folder and then excluding the ones you don't want instead. If you scroll down to the Source Filtering section you'll see how to do that.

Next scroll down to the Generated Documentation section and add a HTML Output Folder line to tell Natural Docs where it should go:

    HTML Output Folder: C:\My Project\Documentation

That's it. Now every time you run Natural Docs with the project configuration folder name on the command line it will search those folders for code and build documentation for it.

    NaturalDocs.exe C:\My Project\ND Config

If the language you're using has full support you'll get usable documentation right away. If it only has basic support, you won't see anything in the output until you document your code.

Upgrading a 1.x Project

If you've already been using Natural Docs 1.x on your code, upgrading is easy. First, delete the contents of your documentation folder so the old files don't get mixed in. You can also delete the Data folder in your project configuration folder. It should only contain .nd files, you don't want to delete any of the .txt files in your project configuration folder.

Now just run the new version with the same command line you used before. Things like this still work:

    NaturalDocs.exe -i c:\My Project\Source
                    -p c:\My Project\ND Config
                    -o HTML C:\My Project\Documentation

That's it. Going forward you can either continue to use the command line or switch to using Project.txt. This is a file in your project configuration folder that stores all the settings that were previously on the command line so in the future you can just run Natural Docs this way:

    NaturalDocs.exe c:\My Project\ND Config

Just give it the project configuration folder on the command line, you don't even need -p anymore. To make changes just edit Project.txt. It also copied a few settings from Menu.txt if you had them, like the project title and copyright. Menu.txt isn't used anymore so you can delete it after the first run. The same goes for Topics.txt; its settings were copied into Comments.txt on the first run and it won't be used going forward.

Next: Documenting Your Code