PixInsight Reference Documentation System

[Juan Conejero]

Hi all,

I am glad to inform you that an integrated documentation system for PixInsight has now been designed and implemented. It will be released with the next version of PixInsight, and is now being used to author the official PixInsight Reference Manual, a collection of reference documents for all standard PixInsight tools.


The Documentation System

The new documentation system consists of four main components:

- A local directory subtree withint PixInsight's installation directory. This subtree contains all reference documents and a number of auxiliary documents and files necessary for the whole system to work, such as style sheets, icons, scripts, etc.

- A set of dedicated user interface resources available in the PixInsight Core application. In particular, tool documentation will be directly accessible from the Process Explorer window.

- The PIDoc markup language. PIDoc is an easy-to-use and easy-to-learn, yet powerful language used to author all PixInsight reference documents. PIDoc allows developers on the PCL and PJSR frameworks to document their tools quickly and efficiently, with virtually perfect isolation between document contents and appearance. You just concentrate on your documentation contents, and PIDoc and the PIDoc compiler (see below) do the rest.

- The PixInsight documentation compiler. The documentation compiler parses PIDoc source code files, generates XHTML/CSS output documents, and automatically integrates them with the local PixInsight reference documentation system.


Available Resources

The PIDoc language and the documentation compiler are now available to interested developers and users. Both are now fully documented and ready-to-use; in fact, we are using them intensively to author the official reference manual.

- Documentation: The PixInsight Reference Documentation System. A thorough description of the PixInsight Reference Documentation System, including the PixInsight documentation compiler and the PIDoc markup language.

- The documentation compiler has been implemented as a script on the PixInsight JavaScript Runtime (PJSR) framework, so it is readily available to all users on all supported platforms. The compiler source code can be downloaded here. To install it, unzip the compressed file on your src/scripts installation directory and use the Script > Feature Scripts main menu item.

- Several examples of documents generated with PIDoc and the PIDoc compiler:

    * The ScreenTransferFunction tool and its PIDoc source code.
    * The CurvesTransformation tool and its PIDoc source code.
    * The BackgroundNeutralization tool and its PIDoc source code.


I hope you like it. As you can see, I am facing the problem of lack of documentation very seriously. PixInsight is a large and complex project and its documentation is also complex. The new system has been designed to implement the documentation that PixInsight deserves. All your ideas and opinions will be welcome, as always.

[Harry page]

Hi

I had to read it twice to make sure 

Good move forward , might help some people 

Harry

[Luigi]

I might be one of those people.

In fact, I read the STF documentation and learned something I didn't know (I always wondered if I could use the STF parameters in the Histogram tool).

Me like.  

[Harry page]

Perhapes I might be able to retire 


Harry

[Emanuele]

Oh my gosh!!
I love it!

This is so awesome!

[DaveS]

What a great addition to PixInsight  8)

Dave

[moladso]

Good job, thanks.

[Redshift]

That's excellent news. 

Dave

[mmirot]

Juan,

I think it is a great way to document the system.  Nice idea.

Max

[Nocturnal]

Leave it up to Juan to do this by implementing a new documentation language I guess XML or HTML weren't good enough. I'll download the compiler and see if I can document my modules with it.

Thanks Juan for addressing this urgent need.

[Andres.Pozo]

Thanks Juan.
You can not do anything by halves 

[Luigi]

Perhapes I might be able to retire 


Harry

Perish the thought.

[Nigel Ball]

Excellent work Juan

I like the layout a lot I think this will be a great help for people like myself who are still finding their way around the software

Documenting any software product efficiently in a user friendly manner is no mean task. In our company we employ a Technical author full time who does nothing other than document our products!

 

[Philip de Louraille]

Just outstanding! Thanks Juan!

[Ioannis Ioannou]

Good. So the next time somebody will complain that PI lacks documentation (eg at CN  ) we will have something to show 
Seriously now, this was really needed, especially for people like me that lack theoretical background and try to find their way by just try-and-error, this will give us a deeper knowledge of the tool.