Getting up to speed with NaturalDocs will only take a few minutes. This article will show you:
- Where to find the NaturalDocs executables
- Where to find commenting guidelines
- Setup a sample project workspace
- Automate NaturalDocs with a simple Windows Batch File
Getting Started
- Download and unpack the latest version of NaturalDocs available at:
http://www.naturaldocs.org/. - Document your code according the NaturalDocs coding guidelines found at:
http://www.naturaldocs.org/documenting.html. - Download this Windows Batch File if you wish to automate the process.
- Create a folder in your project for documentation. Refer to the Project Folder Structure below.
- Run NaturalDocs.bat directly or customize and run the automation batch file.
Setting Your Project’s Folder Structure
The following is an example project structure with separate development and documentation areas:
Customizing the Windows Batch File for Automation
Save the automation batch file in the /documentation/ directory. The batch file contains the following variables:
- NATURAL_DOCS_PATH: Location of the NaturalDocs executable
- INPUT_PATH: Relative path from the automation batch file to the source files
- OUTPUT_PATH: Relative path from the automation batch file to the desired output directory*
- PROJECT_PATH: Relative path from the automation batch file to the desired project directory*
*Set the output path and the project path to the same directory and leave the project data alone to save time on customizations. I usually have two batch files in the documentation directory. Each batch file generates documentation for a different portion of my code (procedural ActionScript and ActionScript classes).
Using NaturalDocs in a Subversion Workspace
NaturalDocs deletes documentation files if the class source file has been renamed or removed. Committing the documentation directories immediately after running NaturalDocs will eliminate errors in your working copy.
NaturalDocs Command Line Options
Refer to http://naturaldocs.org/running.html for more information. The automation batch file uses HTML output instead of HTML-frames output. Modify the last line of the automation batch file to change the output format.
NaturalDocs uses a ‘Project Root’ command-line parameter for storing project data. The project data contains custom menu arrangements, custom keywords, and custom topics. Project data is generated automatically but may be modified after NaturalDocs has generated documentation.