[Insight-developers] developing formal documentation

Thu Sep 13 21:10:31 EDT 2012

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.
> ________________________________
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://www.itk.org/pipermail/insight-developers/attachments/20120913/aed0397c/attachment.htm>