Project.txt

Project.txt is the main configuration file for your project. It's where you tell Natural Docs which folders to scan, where to put the generated documentation, and some other settings like what the name of your project is.

Source Code

You tell Natural Docs which folder to scan for source code with this line:

    Source Folder: C:\My Project\Source

When you run Natural Docs it will convert any absolute paths into ones relative to the project configuration folder. So if you keep your source code in C:\My Project\Source and make your project configuration folder C:\My Project\ND Config, the path will change to ..\Source. This lets Project.txt remain portable across machines and play nice with version control systems. You don't have to worry about typing relative paths though, just putting in absolute ones and letting Natural Docs convert it is fine.

You can have multiple source folders. If you do each one should get a name to distinguish them in the documentation. Natural Docs will make a guess as to what they should be, but you can set them manually for more control.

    Source Folder: C:\My Project\Module A\Source
       Name: Module A

    Source Folder: C:\My Project\Module B\Source
       Name: Module B

If you have a lot of source folders, another option is to use a higher level folder and exclude the ones you don't want instead.

    Source Folder: C:\My Project

    Ignore Source Folder: C:\My Project\Notes
    Ignore Source Folder: C:\My Project\Test Data

Generated Documentation

You tell Natural Docs where to put the generated documentation with this line:

    HTML Output Folder: C:\My Project\Documentation

Project Information

You should always give your project a title in Project.txt. It's what appears in the header of the documentation, on its the front page, and in the HTML page titles.

    Title: My Project

If you want you can also add a subtitle, which is a second, smaller line of text underneath the title, and copyright and timestamp information, which appear on the front page and in the footer.

    Subtitle: Version 1.0

    Copyright: Copyright (C) 2020 Me
    Timestamp: Last updated month day, year

Timestamp performs the following substitutions, so if you were to use "Updated month day, year" it would turn into "Updated January 1st, 2020". If you used "Generated mm-dd-yyyy" it would turn into "Generated 01-01-2020".

m | Single digit month, when possible. January is "1".
mm | Always double digit month. January is "01".
mon | Short month word. January is "Jan".
month | Long month word. January is "January".
d | Single digit day, when possible. 1 is "1".
dd | Always double digit day. 1 is "01".
day | Day with text extension. 1 is "1st".
yy | Double digit year. 2020 is "20".
yyyy | Four digit year. 2020 is "2020".
year | Four digit year. 2020 is "2020".

All of these properties are optional though, so you don't have to include them.

Image Files

By default, when you embed images in your comments it looks for the image file relative to the source file. So if you put (see MyImage.jpg) in C:\MyProject\Source\MyClass.cs, it will look for C:\MyProject\Source\MyImage.jpg. However, you can tell Natural Docs to search additional folders for images with this line:

    Image Folder: C:\My Project\Images

Now it will also look for C:\MyProject\Images\MyImage.jpg. You can specify as many image folders as you want and it will search them all in order.

vs. Command Line

Some of the options in Project.txt can be specified on the command line instead. This is partially for compatibility with Natural Docs 1.x, as Project.txt was introduced in 2.0. The command line is available for those that want it, but Project.txt is the recommended way of working.

Anything specified on the command line will override the settings in Project.txt. Not only that, they will be saved into Project.txt, overwriting any conflicting settings. This allows people who used Natural Docs 1.x to migrate easily, as it will generate a correct Project.txt for them if they run 2.0 with their old command line. It also allows people to continue to use the command line if they choose and only use Project.txt for secondary settings like the project title or the names of source folders.

Settings are handled in four groups: source, source filtering, images, and documentation. Specifing a setting for a group on the command line will override all the Project.txt settings for that group. This means if you use -i to specify a source folder, Natural Docs will view that as the full list of source folders and ignore any in Project.txt that aren't also on the command line. The same goes for the source filters if you use -xi or -xip and the generated documentation if you use -o.

Syntax Reference
Project Information

    Title: [text]

The name of your project. This will appear on the front page, heading, and in the page titles of your documentation. If you use (R) or (TM) they will be converted to their respective symbols.

    Subtitle: [text]

A subtitle for your project. This will appear on the front page and heading of your documentation.

    Copyright: [text]

The copyright notice for your project. This will appear on the front page and footer of your documentation. If you use (C) it will be converted to the copyright symbol.

    Timestamp: [text]

Text explaining when the documentation was generated. This will appear on the front page and footer of your documentation. The following substitutions are performed:

m | Single digit month, when possible. January is "1".
mm | Always double digit month. January is "01".
mon | Short month word. January is "Jan".
month | Long month word. January is "January".
d | Single digit day, when possible. 1 is "1".
dd | Always double digit day. 1 is "01".
day | Day with text extension. 1 is "1st".
yy | Double digit year. 2020 is "20".
yyyy | Four digit year. 2020 is "2020".
year | Four digit year. 2020 is "2020".

So if you were to use "Updated month day, year" it would turn into "Updated January 1st, 2020". If you used "Generated mm-dd-yyyy" it would turn into "Generated 01-01-2020".

    Style: [style]

The style to apply to the generated documentation. It can be the name of a CSS file in the project configuration folder for a simple style or a subfolder that contains Style.txt for an advanced style. Do not include ".css" if using a CSS file.

Source Code

    Source Folder: [path]
       Name: [name]

Specifies a folder which will be searched for source files. If you have more than one, add the Name property to set how it will show up in the menu.

Source Filtering

    Ignore Source Folder: [path]

Tells Natural Docs to skip this folder when scanning files.

    Ignore Source Folder Pattern: [pattern]

Tells Natural Docs to skip all folder names which match this pattern when scanning files. ? matches a single character, * matches zero or more characters. It applies to the entire folder name, so "cli" will not match "client", although "cli*" will.

The data folders of common version control systems (.git, .svn, .cvs, .hg) are ignored automatically. You do not have to specify them here.

Images

    Image Folder: [path]

Specifies a folder which will be searched for image files. They can be referenced in comments with (see filename.jpg).

Generated Documentation

    HTML Output Folder: [path]
       [Project Information]

Generates HTML documentation in the specified folder.

If you want, you can also include any of the project information properties under this line to have them apply to just that folder.

Global Settings

    Tab Width: [width]

The number of spaces tabs should be expanded to.

    Documented Only: [yes|no]

Whether only documented code elements should appear in the output. Defaults to no.

    Auto Group: [yes|no]

Whether groups should automatically apply to you code. Defaults to yes.

Next: Comments.txt