Location: PHPKode > scripts > SourceScribe > rstacruz-SourceScribe/docsrc/01-getting-started.doc.txt
*//////////////////////////////////////////////////////////////////////////////*

Page: SourceScribe manual

## What is SourceScribe?

  SourceScribe is a documentation-generation tool which takes your formatted
  source code comments and creates a full heirarchal manual in HTML or PDF,
  like this one you're viewing now.

  It is written in PHP and is ran from the command line. Being written in PHP,
  it has very little requirements: it can run on any OS that supports PHP4
  (Mac, Linux, Windows) and requires no other libraries.

  This site that you're looking at now is generated by SourceScribe, generated
  from the actual SourceScribe source tree! You're looking at the very output
  of SourceScribe.

Start now:


  <strong>Need amazing documentation for your project?</strong>  
  [Start using SourceScribe! &rarr;](##Using SourceScribe)

Download and contribute:

  This project is hosted in GitHub. You may download [SourceScribe's latest version](http://github.com/rstacruz/sourcescribe/zipball/master)
  there.

  <http://github.com/rstacruz/sourcescribe>

*//////////////////////////////////////////////////////////////////////////////*

Page: Using SourceScribe
[Grouped under "Getting started"]


<big>You can get started using SourceScribe in just 2 minutes!</big>

Get your project written in PHP, Ruby, C, Java, JS, or any other language
documented with a nice manual with these 5 easy steps.

## Dig in right away!

  1. [Download it.](http://github.com/rstacruz/sourcescribe/zipball/master)  
     The latest version is always available in the SourceScribe github page.

  2. [Install it.](##Installing SourceScribe)  
     by extracting the package somewhere, and making a
     symlink to to the *ss* executable from somewhere in your path
     like _/usr/local/bin_.

  3. [Initialize your project.](##Configuration)  
     Go to your project's source directory and type `ss makeconfig` in the
     command line. This will generate the *sourcescribe.conf* file with
     defaults. You may edit it for more options if you wish.

  4. [Document your project.](##Documenting your code)  
     The syntax is easy and natural!

  5. [Run it.](##Generating documentation)  
     Start by typing `ss`. This will generate the documentation for you!

  That's all there is to it!

Continue:

  <strong>Ready to begin?</strong>  
  [Downloading and installing SourceScribe &rarr;](##Installing SourceScribe)

*//////////////////////////////////////////////////////////////////////////////*

Page: Installing SourceScribe
[Grouped under "Getting started"]

Downloading:

  You may download the latest version of SourceScribe from [SourceScribe's
  github page][gh] ([direct link](latest)). If you have **git** installed,
  you may also do a pull of the
  latest sources from the tree. Simply type:

    git pull hide@address.com:rstacruz/sourcescribe.git

  [gh]: http://github.com/rstacruz/sourcescribe/
  [latest]: http://github.com/rstacruz/sourcescribe/zipball/master

Installation:

 - Unzip the entire package somewhere,
   maybe *c:\Program Files\SourceScribe* or *~/sourcescribe/*.

 - **For Mac and Linux:**  
   Make a symbolic link to the file *ss* in a directory that's in your *PATH*
   environment variable. Example:  
   <code>sudo ln -s \`pwd\`/ss /usr/local/bin/ss</code>

 - **For all:**  
   Alternatively, you can add that installation path in the beginning of
   your *PATH* environment variable.

   - For Windows, this is under System Properties &rarr; Advanced Tab &rarr;
     Environment variables &rarr; PATH &rarr; Edit. Add it to the beginning,
     followed by a semi-colon (;).

   - For MacOS/Linux, you can do this by adding the line to your *~/.profile*.
     Example:  
     <code>echo export PATH=/Users/rsc/sourcescribe:\$PATH | tee ~/.profile</code>

## Rock on!

  Once you've installed SourceScribe, you are now ready to configure
  SourceScribe for project. After that, you can start documenting your code,
  and generate your first documentation manual!

Continue:
  <strong>Got it installed?</strong>  
  [Configure SourceScribe for your project! &rarr;](##Configuration)

*//////////////////////////////////////////////////////////////////////////////*

Page: Configuration
[Grouped under "Getting started"]

Starting up:

  For SourceScribe to work on your code, it must first have a configuration file.

  Start by typing `ss makeconfig` in your project folder. This will create a bare
  configuration file `sourcescribe.conf`. It already has defaults, so you don't
  need to edit it at all. After you've done this (and documented your codebase
  of course), you can simply type `ss` to generate your documentation.

  When running `ss`, SourceScribe will look for this `sourcescribe.conf` file.
  SourceScribe will check in the current folder and it's parent folders, so you
  may call `ss` anywhere inside your source tree.

File format:

  The configuration file is in YAML format, which is a simple format for
  defining key/value pairs and arrays.
  
  For more information on this file format, see the [YAML in 5 minutes][l1]
  tutorial, the [YAML Wikipedia entry][l2], or the official [YAML site][l3].

  [l1]: http://yaml.kwiki.org/?YamlInFiveMinutes
  [l2]: http://en.wikipedia.org/wiki/YAML
  [l3]: http://www.yaml.org


Creating your config file:

  In the command line, change to the directory of your project and type
  `ss makeconfig`. This will output a sample `sourcescribe.conf` for you
  to edit to your needs.

Sample file:
  
  Here's a sample file with bare options:  

    # My sourcescribe.conf file
    # Lines starting with pound signs are ignored as comments.
    
    name: My Project
    output:                   # "output" is an array of key-value pairs.
     - driver: "html"
       path: "doc/"
       template: "default"
     - driver: "pdf"
       path: "pdf/"
    exclude:                  # "exclude" is an array.
     - \.svn$
     - \.git$

Another sample:

  The only required options are `name` and `output`. This is also
  a valid configuration file: 

    # sourcescribe.conf
    name: My project
    output: [{ driver: "html", path: "doc/" }]

Required options:

  name
  : The project name. This will be the title of the entire documentation.

    > <code>name: My API reference</code>
   
    A home page for your manual may be created by defining a page with the
    same name listed here.

  output
  : The outputs to spit out. This is an array of key-value pairs, each pair
    requiring a *driver*, and a *path* to define where the output will be
    saved to.

    > <code>output:  
    > - driver: "html"  
    > &nbsp; template: "default"  
    > &nbsp; path: "doc/"</code>

More options:

  src_path
  : The path where the source files are. In this example, SourceScribe will scan
    the *doc* folder (under where the configuration file resides): 

    > <code>src_path: doc</code>

   Multiple paths may also be defined using an array.

    > <code>src_path:  
    > &nbsp; - src  
    > &nbsp; - include</code>

  exclude
  : An array of regex patterns to match filenames against.
    Any file that matches will not be parsed. In this example below,
    SourceScribe will skip files under the folders *.svn*, *.git*, and *cache*:  

    > <code>exclude:  
    > &nbsp; - \.svn/  
    > &nbsp; - \.git/  
    > &nbsp; - /cache/</code>

Advanced options:

   More advanced options are available. [[Advanced configuration]].

Continue:

  <strong>Configuration all set?</strong>  
  [Start documenting your code! &rarr;](##Documenting your code)

*//////////////////////////////////////////////////////////////////////////////

// Page: Documenting your code
// [Grouped under "Getting started"]
// 
// Do something like
// 
//     /*
//      * Class: MyClass
//      * This is my classname.
//      *
//      * More documentation goes here.
//      */
//     class MyClass
//     {
//         ...
// 
// And stuff!
// 
// Continue:
// 
//   <strong>Let's make documentation!</strong>  
//   [Generating documentation &rarr;](##Generating documentation)

//////////////////////////////////////////////////////////////////////////////*

Page: Generating documentation
[Grouped under "Getting started"]

  Type `ss`. That's all there is to it! To open it in your browser,
  type `ss open`.

## You're done!

  You have just finished configuring your project to use SourceScribe,
  documenting it, and generating documentation for it.

*//////////////////////////////////////////////////////////////////////////////*
Return current item: SourceScribe