Configuring and Running
3x Faster

Natural Docs 2.0 is much faster than the Perl version. I timed them building 2.0's source documentation from scratch several times, both cold after a reboot and warm, and it always finished at least 3x faster, sometimes more.

On a 2012-era laptop (Core i5-3317U) a full build with version 1.52 would take about a minute. Using 2.0 on the same laptop takes around 20 seconds, 3 times faster! On a much stronger desktop PC (Core i7-6700) a full build with 1.52 would still take around 30 seconds, whereas with 2.0 it takes less than 10. This also means the old laptop with 2.0 is faster than the desktop PC with 1.52!

Natural Docs 2.0 is fully multi-threaded so it can take advantage of multi-core CPUs. The Perl version cannot. However, even if you force it to use only one worker thread it's still 50-80% faster than 1.52.

And remember, the new version is still differential, which means the only time you'll see a wait like this is the first time you build your documentation. Every time you run it afterwards it detects what changed and only updates what's necessary. It's fast enough to let you continuously update your own copy while you work.

Project File

You managed things like input folders, output folders, and filtering on the command line in Natural Docs 1.x. You can still do that with 2.0, but those settings and more can be found in a new configuration file called Project.txt.

Getting started with it is easy. If you have an existing project, just run Natural Docs 2.0 with the same command line you had before. It will create a Project.txt file for you with those settings, plus a few copied from Menu.txt. Then going forward you can change the command line to just "NaturalDocs.exe [project folder]". You don't even need -p anymore.

If you're starting a new project, run "NaturalDocs.exe [project folder]" pointing it to an empty folder and it will generate the default configuration files for you to edit.

If you still prefer to use the command line for these settings you can. Anything on the command line will override the settings in Project.txt and you can just use it for secondary settings.

New Style System

Natural Docs has a new style system. In 1.x you could only specify a single CSS file. That's still supported for the people who just want to make a tweak or two, but now you can also build more sophisticated styles that include images and JavaScript.

To do this you would create a subfolder in your project configuration folder and put a Style.txt configuration file in it. Any assets you include in that folder will be copied to the output folder, and in Style.txt you can specify how to link them to the different types of pages, which styles you want to inherit from, and any custom OnLoad() code you want to include.

The default styles are built with this system, and there's actually two of them. You can make your own styles inherit from Default, which includes everything and you just make your adjustments on top of it, or if you want to start from scratch visually you can inherit from DefaultJS, which only includes the JavaScript and none of the CSS or images.

Better Filtering

You can now filter out folders by pattern instead of just by path with -xip on the command line or "Ignore Source Folder Pattern" in Project.txt. This means you can add folder names that appear in multiple places like "bin" and "obj" and it will ignore them everywhere. You can also use * and ? wildcards.

Common version control system folders .git, .svn, .hg, and .cvs will be filtered out automatically. You don't have to add them yourself.

Comments.txt

Not a new feature but just so you're aware, Topics.txt has been changed to Comments.txt. In the course of writing all the references and guides for the new web site I found that referring to "comments" instead of "topics" was usually clearer, and 90% of the time there's no distinction from the end user's perspective. I decided to banish "topics" and "topic types" as unnecessary terminology. They're just "comments" and "comment types" now, and with that comes corresponding changes in Topics.txt, which is now Comments.txt.

The first time you run Natural Docs 2.0 on an old project it will convert it for you automatically. The old Topics.txt won't be deleted though, so you may want to do that yourself since you won't need it anymore.

Next: What's Missing