Re: Synopsis as documentation tool

On 12/12/05, Stefan Seefeld <[email protected]> wrote:
> Roman Yakovenko wrote:
> > 1. How do I specify project name?
>
> What is a project ?

Good question. I am going to create documentation to 2 my projects:
pygccxml and pyplusplus (http://www.language-binding.net/ )

Both projects written in Python and consist from few packages.

> > 2. How do I tell Synopsis to work on whole package recursively?
>
> I deliberately avoided putting this kind of functionality into synopsis,
> as that requires dependency management, something that is much better dealt with
> by build tools such as 'make'.

Okey, I understand the answer, and now I have an other question:
How I create complete set of documentation for whole project? Do
Synopsis has some
"merge" functionality?

> > 3. What is the special syntax for comments\documentation string Synopsis uses?
>
> http://synopsis.fresco.org/docs/Tutorial/comments.html

Yes, I saw this page. It says nothing about Python

> > 4. How do I specify in documentation string the type of variable\argument?
> >     ( I would like to have some link to the variable class definition
> > in generated documentation )
>
> I'm not sure I understand what you are asking. You can always explicitely
> insert links using something like '@see'. The type of a parameter is
> obtained by inspecting the source code, not the comment, so you shouldn't
> duplicate that information.

Not in my case. :-)

> > I understand that the best way to use Synopsis is to write my own
> > Synopsis script,
> > as is shown here http://synopsis.fresco.org/docs/Tutorial/script.html.
> > But I would like to evaluate it first.
>
> Scripting is useful when you want to fine-tune the processing. For
> simple cases the 'synopsis' application should be enough.

I prefer to write some script, because this way it is much easier to integrate
documentation generation in build process.

> Regards,
>                 Stefan


Thanks

Roman Yakovenko