Dear Git Community: My organization is exploring using Git to manage our code repository. We also have a strong need for documentation of our code. The code is written in a proprietary language (Discern Explorer/CCL). We looked into Natural Docs but don't think we can combine it with Git. Does anyone know of an app where we can combine the power of Git and code documentation in one? Thank you. -Sultan
Ævar Arnfjörð BjarmasonRe: Git and Documentation
On Mon, Aug 9, 2010 at 17:35, Sultan Shakir <sshakirflhosp@gmail.com> wrote:
Show 7 quoted lines
> Dear Git Community: > My organization is exploring using Git to manage our code repository. > We also have a strong need for documentation of our code. The code is > written in a proprietary language (Discern Explorer/CCL). We looked > into Natural Docs but don't think we can combine it with Git. Does > anyone know of an app where we can combine the power of Git and code > documentation in one? Thank you. -Sultan
Can you be clearer. That question makes little sense.
You can keep your documentation *in* Git if it's in files that you can keep in version control. So in that case you could keep it alongside your code.
Can't you use this approach?
Re: Git and Documentation
Yes I guess I could. I am a little new at this. I got the same idea after watching Stephen Wood's video here: http://developer.yahoo.com/yui/theater/video.php?v=woods-yuiconf2009-yuidoc . He had 3 rules/guidelines that might work if we use YUI Doc to generate the documentation:
1) Generate documentation as part of the build 2) Don’t manually check documentation in to VCS (do it automatically) 3) Treat documentation comments like code
I am not sure how to make it run as part of my build process though.
On Mon, Aug 9, 2010 at 4:43 PM, Ævar Arnfjörð Bjarmason <avarab@gmail.com> wrote:
Show 17 quoted lines
> On Mon, Aug 9, 2010 at 17:35, Sultan Shakir <sshakirflhosp@gmail.com> wrote: >> Dear Git Community: >> My organization is exploring using Git to manage our code repository. >> We also have a strong need for documentation of our code. The code is >> written in a proprietary language (Discern Explorer/CCL). We looked >> into Natural Docs but don't think we can combine it with Git. Does >> anyone know of an app where we can combine the power of Git and code >> documentation in one? Thank you. -Sultan > > Can you be clearer. That question makes little sense. > > You can keep your documentation *in* Git if it's in files that you can > keep in version control. So in that case you could keep it alongside > your code. > > Can't you use this approach? >
Tomas CarneckyRe: Git and Documentation
On 8/10/10 9:55 PM, Sultan Shakir wrote:
Show 11 quoted lines
> Yes I guess I could. I am a little new at this. I got the same idea > after watching Stephen Wood's video here: > http://developer.yahoo.com/yui/theater/video.php?v=woods-yuiconf2009-yuidoc > . He had 3 rules/guidelines that might work if we use YUI Doc to > generate the documentation: > > 1) Generate documentation as part of the build > 2) Don’t manually check documentation in to VCS (do it automatically) > 3) Treat documentation comments like code > > I am not sure how to make it run as part of my build process though.
Please don't top post.
If the documentation is generated as part of the build, then there is no reason to have it part of the history - you can always rebuild it from the source. For the same reason you don't put compiled source into git.
And how to generate the doc as part of the build? That's up to you and very much depends on what build system you use.
tom
Michael WittenRe: Git and Documentation
On Tue, Aug 10, 2010 at 15:31, Tomas Carnecky <tom@dbservice.com> wrote:
> If the documentation is generated as part of the build, then there is no > reason to have it part of the history - you can always rebuild it from > the source. For the same reason you don't put compiled source into git.
Well, theoretically.
According to:
http://git.kernel.org/?p=git/git.git;a=blob_plain;f=MaintNotes;hb=todo
the git project's repository itself tracks generated documentation for practical reasons:
The "html" and "man" [branches] are autogenerated documentation from the tip of the "master" branch; the tip of "html" is extracted to be visible at kernel.org at:
http://www.kernel.org/pub/software/scm/git/docs/
Michael WittenRe: Git and Documentation
On Tue, Aug 10, 2010 at 15:47, Michael Witten <mfwitten@gmail.com> wrote:
Show 22 quoted lines
> On Tue, Aug 10, 2010 at 15:31, Tomas Carnecky <tom@dbservice.com> wrote: >> If the documentation is generated as part of the build, then there is no >> reason to have it part of the history - you can always rebuild it from >> the source. For the same reason you don't put compiled source into git. > > Well, theoretically. > > According to: > > http://git.kernel.org/?p=git/git.git;a=blob_plain;f=MaintNotes;hb=todo > > the git project's repository itself tracks generated documentation for > practical reasons: > > The "html" and "man" [branches] are > autogenerated documentation from the > tip of the "master" branch; the tip > of "html" is extracted to be visible > at kernel.org at: > > http://www.kernel.org/pub/software/scm/git/docs/ >
I should add that generating documentation is time consuming and often requires brittle software; there's a lot to gain by having one system produce the same output for virtually everyone else.
Re: Git and Documentation
On Tue, Aug 10, 2010 at 4:56 PM, Michael Witten <mfwitten@gmail.com> wrote:
Show 28 quoted lines
> On Tue, Aug 10, 2010 at 15:47, Michael Witten <mfwitten@gmail.com> wrote: >> On Tue, Aug 10, 2010 at 15:31, Tomas Carnecky <tom@dbservice.com> wrote: >>> If the documentation is generated as part of the build, then there is no >>> reason to have it part of the history - you can always rebuild it from >>> the source. For the same reason you don't put compiled source into git. >> >> Well, theoretically. >> >> According to: >> >> http://git.kernel.org/?p=git/git.git;a=blob_plain;f=MaintNotes;hb=todo >> >> the git project's repository itself tracks generated documentation for >> practical reasons: >> >> The "html" and "man" [branches] are >> autogenerated documentation from the >> tip of the "master" branch; the tip >> of "html" is extracted to be visible >> at kernel.org at: >> >> http://www.kernel.org/pub/software/scm/git/docs/ >> > > I should add that generating documentation is time consuming and often > requires brittle software; there's a lot to gain by having one system > produce the same output for virtually everyone else. >
Thank you all.