[Insight-developers] developing formal documentation

Fri Sep 14 09:07:03 EDT 2012

Hi Hans, Brian, Michael,

I will not be able to make the October meeting, but I concur that
generating the next stage of the Software Guide is very important, we
should consolidate efforts, and we should avoid hard to maintain
line-number references.

Thanks,
Matt

On Thu, Sep 13, 2012 at 9:10 PM, brian avants <stnava at gmail.com> wrote:
> Everyone,
>
> Great.   Let's discuss @ the oct meeting.   I've used all the mentioned
> approaches, including sphinx.
>
> I think we need to invent something that does not use line numbers.  Its
> doable.
>
> Anyway, discuss in october.
>
> B
>
> On Sep 13, 2012 8:53 PM, "Johnson, Hans J" <hans-johnson at uiowa.edu> wrote:
>>
>> Brian and Matt and others,
>>
>> Could we talk about this during the October meeting?  I've also negotiated
>> some protected time from my department (in December/January) to work on
>> updating the software guide.  I've also got some outstanding JIRA tickets
>> that are related to preparing for a new software guide, along with many
>> fixes to the comments and code in ITK over the past year.
>>
>> I've got some outlines of material that is no longer relevant, and notes
>> from my course teachings about deficiencies/outdated materials that
>> mislead the user on how the toolkit should be used because it had evolved
>> away from the original documentation.
>>
>> It is my feeling that this is a VERY important document for the community,
>> and it has been neglected for far too long.  My git hub repository has
>> focused on the build/extration mechanism and it has a 95% rewrite of the
>> extraction process written in python, and I've also worked on updating the
>> graphics and style of LaTeX.
>>
>> Please let me know if you will be at the October meeting so that we can
>> keep from duplicating efforts.
>>
>> Hans
>>
>>
>> On 9/13/12 7:45 PM, "Matt McCormick" <matt.mccormick at kitware.com> wrote:
>>
>> >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
>> >_______________________________________________
>> >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
>>
>>
>>
>> ________________________________
>> Notice: This UI Health Care e-mail (including attachments) is covered by
>> the Electronic Communications Privacy Act, 18 U.S.C. 2510-2521, is
>> confidential and may be legally privileged.  If you are not the intended
>> recipient, you are hereby notified that any retention, dissemination,
>> distribution, or copying of this communication is strictly prohibited.
>> Please reply to the sender that you have received the message in error, then
>> delete it.  Thank you.
>> ________________________________