[Insight-developers] developing formal documentation

Thu Sep 13 21:47:38 EDT 2012

Brian, the previous software guide used custom scripts available in the documentation repo. These process markups within the source code for the sections to be extracted and included in documentation. So we probably needn't invent anything new in that regard, seeing as these scripts could be repurposed even if the new documentation is done in sphinx.

-M

  _____  

From: insight-developers-bounces at itk.org [mailto:insight-developers-bounces at itk.org] On Behalf Of brian avants
Sent: Thursday, September 13, 2012 9:11 PM
To: Johnson, Hans J
Cc: Terry Yoo; ITK-dev-list-mstauff at ver
Subject: Re: [Insight-developers] developing formal documentation

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/e88153b5/attachment.htm>