API Help and developer guide

classic Classic list List threaded Threaded
5 messages Options
Reply | Threaded
Open this post in threaded view
|

API Help and developer guide

John Prikkel

 

What format for API documentation and a developer guide do you want to see in the future?

 

Here are some options:

 

1) HTML help generated from doxygen

2) Integrated API documentation with your compiler (like Visual Studio)

3) A Wiki that anyone can edit and add examples

4) A printable manual or PDF.

5) some combination of the above.

 

A draft of a developer’s guide has been started here:

 

http://en.wikibooks.org/wiki/Opticks_Developer_Guide

 

Here is the full document:

 

http://en.wikibooks.org/wiki/Opticks_Developer_Guide/Print_version

 

Thanks,

John

 


This message and any enclosures are intended only for the addressee.  Please  
notify the sender by email if you are not the intended recipient.  If you are  
not the intended recipient, you may not use, copy, disclose, or distribute this  
message or its contents or enclosures to any other person and any such actions  
may be unlawful.  Ball reserves the right to monitor and review all messages  
and enclosures sent to or from this email address.
Reply | Threaded
Open this post in threaded view
|

RE: API Help and developer guide

Bivens, Hugh P

I vote for #1 and #3. I really like the wiki.

 

The main thing for me is to be able to transfer and access tutorials/docs on a standalone network.

 

-Hugh

 


From: Prikkel, John [mailto:[hidden email]]
Sent: Wednesday, July 02, 2008 11:21 AM
To: [hidden email]
Subject: API Help and developer guide

 

 

What format for API documentation and a developer guide do you want to see in the future?

 

Here are some options:

 

1) HTML help generated from doxygen

2) Integrated API documentation with your compiler (like Visual Studio)

3) A Wiki that anyone can edit and add examples

4) A printable manual or PDF.

5) some combination of the above.

 

A draft of a developer’s guide has been started here:

 

http://en.wikibooks.org/wiki/Opticks_Developer_Guide

 

Here is the full document:

 

http://en.wikibooks.org/wiki/Opticks_Developer_Guide/Print_version

 

Thanks,

John

 


This message and any enclosures are intended only for the addressee.  Please  
notify the sender by email if you are not the intended recipient.  If you are  
not the intended recipient, you may not use, copy, disclose, or distribute this  
message or its contents or enclosures to any other person and any such actions  
may be unlawful.  Ball reserves the right to monitor and review all messages  
and enclosures sent to or from this email address.
Reply | Threaded
Open this post in threaded view
|

RE: API Help and developer guide

tclarke
Administrator
In reply to this post by John Prikkel
RE: API Help and developer guide

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

I personally like the HTML help…I’m not a fan of the visual studio integrated help because their help browser is slow and has a lot of overhead with very little value added. I also don’t like a printed manual for reference as it’s usually easier to search soft copy. The wiki could be useful for tutorials, etc. but not for class references. The API is written using literate programming techniques so the code and documentation is highly correlated and we wouldn’t want to lose that correlation…it would lead to lots of duplication and more work to keep the reference documentation up to date.



That said, doxygen can very easily generate a chm which may be usable in visual studio and it can generate LaTeX which can create printable/pdf documentation. All we need to do it set a switch in the doxygen config file and package up the result.



________________________________

From: Prikkel, John [[hidden email]]
Sent: Wednesday, July 02, 2008 1:21 PM
To: [hidden email]
Subject: API Help and developer guide





What format for API documentation and a developer guide do you want to see in the future?



Here are some options:



1) HTML help generated from doxygen

2) Integrated API documentation with your compiler (like Visual Studio)

3) A Wiki that anyone can edit and add examples

4) A printable manual or PDF.

5) some combination of the above.



A draft of a developer’s guide has been started here:



http://en.wikibooks.org/wiki/Opticks_Developer_Guide



Here is the full document:



http://en.wikibooks.org/wiki/Opticks_Developer_Guide/Print_version



Thanks,

John





This message and any enclosures are intended only for the addressee.  Please 
notify the sender by email if you are not the intended recipient.  If you are 
not the intended recipient, you may not use, copy, disclose, or distribute this 
message or its contents or enclosures to any other person and any such actions 
may be unlawful.  Ball reserves the right to monitor and review all messages 
and enclosures sent to or from this email address.
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.6 (MingW32)

iD8DBQFIa9Ja+xUTKUxH/LkRApUFAKCHxarKzyxQxPsimcJYDGOIO7W3rgCeOCng
ypOE4C9A3XHLTTWtj8+93BQ=
=EAd3
-----END PGP SIGNATURE-----


This message and any enclosures are intended only for the addressee.  Please  
notify the sender by email if you are not the intended recipient.  If you are  
not the intended recipient, you may not use, copy, disclose, or distribute this  
message or its contents or enclosures to any other person and any such actions  
may be unlawful.  Ball reserves the right to monitor and review all messages  
and enclosures sent to or from this email address.

---------------------------------------------------------------------
To unsubscribe, e-mail: [hidden email]
For additional commands, e-mail: [hidden email]

PGPexch.htm (11K) Download Attachment
PGPexch.htm.asc (270 bytes) Download Attachment
Reply | Threaded
Open this post in threaded view
|

RE: RE: API Help and developer guide

John Prikkel
RE: API Help and developer guide

Help integration with Visual Studio would give you the capability to hit “F1” or use the dynamic help viewer to quickly get documentation on a class. However, it looks like Visual Studio 2003 and higher use something called “HTML Help 2”, which isn’t the same as CHM.

 

BTW: It looks like Qt Assistant has a tool to take the output of Doxygen and make one of their Qt compressed help files.

 

http://labs.trolltech.com/blogs/2008/06/20/introducing-doxygen2qthelp-create-qch-files-from-doxygen-finally/#comments

 

However, it needs features that will be in Qt 4.4.1, which isn’t released yet. You have to build it from a snapshot from 2008-04-24 or later.

 

John

 


From: Clarke, Trevor [mailto:[hidden email]]
Sent: Wednesday, July 02, 2008 3:09 PM
To: [hidden email]
Subject: RE: API Help and developer guide

 

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

I personally like the HTML help…I’m not a fan of the visual studio integrated help because their help browser is slow and has a lot of overhead with very little value added. I also don’t like a printed manual for reference as it’s usually easier to search soft copy. The wiki could be useful for tutorials, etc. but not for class references. The API is written using literate programming techniques so the code and documentation is highly correlated and we wouldn’t want to lose that correlation…it would lead to lots of duplication and more work to keep the reference documentation up to date.



That said, doxygen can very easily generate a chm which may be usable in visual studio and it can generate LaTeX which can create printable/pdf documentation. All we need to do it set a switch in the doxygen config file and package up the result.



________________________________

From: Prikkel, John [[hidden email]]
Sent: Wednesday, July 02, 2008 1:21 PM
To: [hidden email]
Subject: API Help and developer guide





What format for API documentation and a developer guide do you want to see in the future?



Here are some options:



1) HTML help generated from doxygen

2) Integrated API documentation with your compiler (like Visual Studio)

3) A Wiki that anyone can edit and add examples

4) A printable manual or PDF.

5) some combination of the above.



A draft of a developer’s guide has been started here:



http://en.wikibooks.org/wiki/Opticks_Developer_Guide



Here is the full document:



http://en.wikibooks.org/wiki/Opticks_Developer_Guide/Print_version



Thanks,

John





This message and any enclosures are intended only for the addressee.  Please 
notify the sender by email if you are not the intended recipient.  If you are 
not the intended recipient, you may not use, copy, disclose, or distribute this 
message or its contents or enclosures to any other person and any such actions 
may be unlawful.  Ball reserves the right to monitor and review all messages 
and enclosures sent to or from this email address.
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.6 (MingW32)

iD8DBQFIa9Ja+xUTKUxH/LkRApUFAKCHxarKzyxQxPsimcJYDGOIO7W3rgCeOCng
ypOE4C9A3XHLTTWtj8+93BQ=
=EAd3
-----END PGP SIGNATURE-----


This message and any enclosures are intended only for the addressee.  Please  
notify the sender by email if you are not the intended recipient.  If you are  
not the intended recipient, you may not use, copy, disclose, or distribute this  
message or its contents or enclosures to any other person and any such actions  
may be unlawful.  Ball reserves the right to monitor and review all messages  
and enclosures sent to or from this email address.

This message and any enclosures are intended only for the addressee.  Please  
notify the sender by email if you are not the intended recipient.  If you are  
not the intended recipient, you may not use, copy, disclose, or distribute this  
message or its contents or enclosures to any other person and any such actions  
may be unlawful.  Ball reserves the right to monitor and review all messages  
and enclosures sent to or from this email address.
Reply | Threaded
Open this post in threaded view
|

RE: RE: RE: API Help and developer guide

tclarke
Administrator
RE: RE: RE: API Help and developer guide

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

Here’s instructions on generate Help 2.x (.hxs) files from doxygen. Basically, you generate a Help 1.x (.chm) from doxygen, then use tools from Microsoft’s Help Workshop to convert the chm to hxs. There are a couple of files that need to be created manually as well. It doesn’t look insurmountable however.



http://wiki.services.openoffice.org/wiki/Integrate_Custom_Help_Into_MSDEV





________________________________

From: Prikkel, John [[hidden email]]
Sent: Wednesday, July 02, 2008 3:26 PM
To: [hidden email]
Subject: RE: RE: API Help and developer guide



Help integration with Visual Studio would give you the capability to hit “F1” or use the dynamic help viewer to quickly get documentation on a class. However, it looks like Visual Studio 2003 and higher use something called “HTML Help 2”, which isn’t the same as CHM.



BTW: It looks like Qt Assistant has a tool to take the output of Doxygen and make one of their Qt compressed help files.



http://labs.trolltech.com/blogs/2008/06/20/introducing-doxygen2qthelp-create-qch-files-from-doxygen-finally/#comments



However, it needs features that will be in Qt 4.4.1, which isn’t released yet. You have to build it from a snapshot from 2008-04-24 or later.



John



________________________________

From: Clarke, Trevor [[hidden email]]
Sent: Wednesday, July 02, 2008 3:09 PM
To: [hidden email]
Subject: RE: API Help and developer guide



- -----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

I personally like the HTML help…I’m not a fan of the visual studio integrated help because their help browser is slow and has a lot of overhead with very little value added. I also don’t like a printed manual for reference as it’s usually easier to search soft copy. The wiki could be useful for tutorials, etc. but not for class references. The API is written using literate programming techniques so the code and documentation is highly correlated and we wouldn’t want to lose that correlation…it would lead to lots of duplication and more work to keep the reference documentation up to date.



That said, doxygen can very easily generate a chm which may be usable in visual studio and it can generate LaTeX which can create printable/pdf documentation. All we need to do it set a switch in the doxygen config file and package up the result.



________________________________

From: Prikkel, John [[hidden email]]
Sent: Wednesday, July 02, 2008 1:21 PM
To: [hidden email]
Subject: API Help and developer guide





What format for API documentation and a developer guide do you want to see in the future?



Here are some options:



1) HTML help generated from doxygen

2) Integrated API documentation with your compiler (like Visual Studio)

3) A Wiki that anyone can edit and add examples

4) A printable manual or PDF.

5) some combination of the above.



A draft of a developer’s guide has been started here:



http://en.wikibooks.org/wiki/Opticks_Developer_Guide



Here is the full document:



http://en.wikibooks.org/wiki/Opticks_Developer_Guide/Print_version



Thanks,

John





This message and any enclosures are intended only for the addressee.  Please
notify the sender by email if you are not the intended recipient.  If you are
not the intended recipient, you may not use, copy, disclose, or distribute this
message or its contents or enclosures to any other person and any such actions
may be unlawful.  Ball reserves the right to monitor and review all messages
and enclosures sent to or from this email address.
- -----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.6 (MingW32)

iD8DBQFIa9Ja+xUTKUxH/LkRApUFAKCHxarKzyxQxPsimcJYDGOIO7W3rgCeOCng
ypOE4C9A3XHLTTWtj8+93BQ=
=EAd3
- -----END PGP SIGNATURE-----



This message and any enclosures are intended only for the addressee.  Please 
notify the sender by email if you are not the intended recipient.  If you are 
not the intended recipient, you may not use, copy, disclose, or distribute this 
message or its contents or enclosures to any other person and any such actions 
may be unlawful.  Ball reserves the right to monitor and review all messages 
and enclosures sent to or from this email address.


This message and any enclosures are intended only for the addressee.  Please 
notify the sender by email if you are not the intended recipient.  If you are 
not the intended recipient, you may not use, copy, disclose, or distribute this 
message or its contents or enclosures to any other person and any such actions 
may be unlawful.  Ball reserves the right to monitor and review all messages 
and enclosures sent to or from this email address.
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.6 (MingW32)

iD8DBQFIa9jB+xUTKUxH/LkRAju7AJ9ZskgJYVqodiuaddxN2AqbQBiaywCfby7y
YASOvKxXuPgxc2nbXXY+vG4=
=uGdj
-----END PGP SIGNATURE-----


This message and any enclosures are intended only for the addressee.  Please  
notify the sender by email if you are not the intended recipient.  If you are  
not the intended recipient, you may not use, copy, disclose, or distribute this  
message or its contents or enclosures to any other person and any such actions  
may be unlawful.  Ball reserves the right to monitor and review all messages  
and enclosures sent to or from this email address.

---------------------------------------------------------------------
To unsubscribe, e-mail: [hidden email]
For additional commands, e-mail: [hidden email]

PGPexch.htm (15K) Download Attachment
PGPexch.htm.asc (270 bytes) Download Attachment