Synopsis is a command-line tool, however a GUI may be included in future releases. Due to the highly configurable nature of Synopsis, it is not feasible to make a command line switch for each option. In order to aide testing and debugging of your configuration however, some of the more common options do have command line switches.
So, the main way to configure Synopsis is with a config file, which is actually a Python script (usually config.py). This script is executed in a sandbox by Synopsis, and then its namespace is inspected to extract the configuration options. If you already know Python then you will have no problems reading and writing the script, and if you don't, well Python is really easy to learn - the Python tutorial included with Python will get you up to speed in half an hour or less! You don't need to know any of the builtin functions or libraries to write a config script.
Synopsis uses three stages to generate documentation: parsing each source file to an AST (Abstract Syntax Tree), linking ASTs together and performing manipulations, and formatting the final AST. There are two ways to control this process:
Use a Makefile, and run Synopsis multiple times. This allows you to integrate Synopsis with your existing build system. A simple Makefile has three rules: one to parse each source file to a .syn file, another to link all the .syn files into a single .syn file, and a third to format the final .syn file. All the configuration is stored in the config.py file and the only switches given to Synopsis are to indicate the stage of processing and the input/output filenames/directories.
Use a Synopsis Project file. Project files are a new paradigm invented for the upcoming GUI which allows the entire process to execute with one synopsis command (eg: synopsis -P project.synopsis). It has some rules similar to make, with the exception that it does proper dependency checking and has flexible rules for selecting input files. The only downside is that in order to make the file easily readable and writable by the GUI it is much less readable and writable by hand.
This manual will concentrate on the Makefile and config.py method, as this is the simplest to learn. All of the configuration options are valid in both files, with the exception of those for controlling the processing of the three stages in the second method.
Synopsis can also integrate your project's documentation across multiple separate libraries or modules. An example is the best way to illustrate this: The Fresco Project has a Reference Manual for its IDL interfaces and its many implementation libraries and modules available online. Your project is a module which integrates with Fresco's display server, using both the IDL API and the display server's internal API. By downloading a .toc file (Table Of Contents) from the Fresco website, the documentation you generate for your project can link directly to Fresco's online documentation. For example, you have a method change_picture(Graphic g) where Graphic is an interface from the IDL API. In your documentation, Graphic will be a hyperlink to the documentation of the Graphic interface at the Fresco website. Neat huh? The Fresco documentation itself uses this feature to generate the documentation for each library separately, using .toc files to link to documentation of the libraries each library uses. See the HTML formatter section for more information.