[Insight-developers] developing formal documentation

[Matt McCormick]

Hi Brian and Michael,

Your documentation efforts for the registration v4 would be be greatly
appreciated by the community.

Regarding where to place the documentation, there is not one clear
answer at this point.  There have been various efforts to start a v4
version of the Software Guide including this one by Arnaud:

  https://github.com/InsightSoftwareConsortium/ITKSoftwareGuide

This one by Hans:

  https://github.com/hjmjohnson/ITKSoftwareGuide

And this one by myself, Arnaud, and David Doria intended to contain
examples separate from "guide" material:

  https://github.com/InsightSoftwareConsortium/ITKExamples
  http://itk.org/ITKExamples/

Maybe there are others, too.  As far as I know, none are "complete",
i.e. they do not have all the material from the v3 Software Guide.  I
am semi-actively working on the last.  I think picking any one of
these to start adding content would not be a bad choice, because it
can always be aggregated in the future.

Re: code and line numbers: I think the one Hans was working is based
off the same previous perl parser (he may correct me).  The first and
third are based on Sphinx:

  http://sphinx.pocoo.org/

A powerful, popular, elegant documentation system.  For sphinx, either
the entire file can be included or a section of the file.  However,
the sections are specified by line numbers.  While I looked quite hard
for a way to not use line numbers, it appears to be the best option at
this point.  At least two copies of the code are not maintained, and
everything that is presented is also tested.

Thanks,
Matt

On Thu, Sep 13, 2012 at 7:56 PM, brian avants <stnava at gmail.com> wrote:
> following up on this ...
>
> ideally, we would like to extract sections of code already in the ITK
> main repository with directives that allow it to be included in a
> latex document.
>
> for example
>
> // \begin{AddToLatexSectionX}
> ...some code
> // \end{AddToLatexSectionX}
>
> as opposed to just extracting line numbers from the source code.
> that's a problem because the line numbers can change over time which
> will create  a dual maintenance and testing issue.
>
> is there an established way of doing this?  if not, we can establish
> our own approach if it's acceptable to  pollute some testing code with
> directives like those above.
>
> thanks, as usual, for your time,
>
> brian
>
>
>
>
> On Thu, Sep 13, 2012 at 6:32 PM, M Stauffer -V- <mstauff at verizon.net> wrote:
>> Hi,
>>
>> Brian Avants and I are working on more formal end-user documentation for
>> the new v4 registration framework.
>>
>> Our first thought is to develop something along the lines of the v3 "ITK
>> Software Guide". Any reason we should take a different approach?
>>
>> We'd like to incorporate code from existing examples directly by
>> reference to the example source code files, as the software guide does.
>> I downloaded the documentation project directly via
>>
>> cvs -d :pserver:anonymous at www.itk.org:/cvsroot/Insight checkout
>> InsightDocuments
>>
>> First off, is this the latest version of this? It's referenced in the
>> main itk.git repo's Documentation/README.html.
>>
>> Within this branch/directory, I see instructions and the scripts for
>> parsing latex-marked-up source code files in
>> InsightDocs/InsightDocuments/SoftwareGuide, for example
>> ParseCxxExamples.pl. These seem to be the documents I need to follow the
>> same approach as the software guide - might there be other instructions
>> or helpful files elsewhere?
>>
>> -M
>>
>> _______________________________________________
>> Powered by www.kitware.com
>>
>> Visit other Kitware open-source projects at
>> http://www.kitware.com/opensource/opensource.html
>>
>> Kitware offers ITK Training Courses, for more information visit:
>> http://kitware.com/products/protraining.php
>>
>> Please keep messages on-topic and check the ITK FAQ at:
>> http://www.itk.org/Wiki/ITK_FAQ
>>
>> Follow this link to subscribe/unsubscribe:
>> http://www.itk.org/mailman/listinfo/insight-developers
> _______________________________________________
> Powered by www.kitware.com
>
> Visit other Kitware open-source projects at
> http://www.kitware.com/opensource/opensource.html
>
> Kitware offers ITK Training Courses, for more information visit:
> http://kitware.com/products/protraining.php
>
> Please keep messages on-topic and check the ITK FAQ at:
> http://www.itk.org/Wiki/ITK_FAQ
>
> Follow this link to subscribe/unsubscribe:
> http://www.itk.org/mailman/listinfo/insight-developers