Re: Documenting python code using LyX

[Guenter Milde]

On 2009-10-20, Wolfgang Keller wrote:
 Does anybody use LyX to document python code? Any hints?

 PyLit already allows to round-trip between Python code with embedded
 ReST comments and ReST documents with embedded Python code blocks. From
 ReST, you can then convert to LaTeX, which should be somewhat
 importable to LyX.

 However, I haven't found a possibility yet to export ReST with embedded
 Python code blocks from Lyx.

Indeet this is a one-way conversion currently. (My suggestion was
rather to use PyLit (together with your (or my) favourite text editor)
*instead of* LyX rather than PyLit with LyX for literal programming.

 Full round-tripping between LyX and Python (or any other programming
 language) code with embedded ReST comments would be pretty close to
 The Holy Grail Of Literate Programming imho. *duck*

Adding native ReST export (and maybe import) to LyX was alredy
discussed once. Maybe some day...

Günter

Re: Documenting python code using LyX

[Guenter Milde]

On 2009-10-20, Wolfgang Keller wrote:
 Does anybody use LyX to document python code? Any hints?

 PyLit already allows to round-trip between Python code with embedded
 ReST comments and ReST documents with embedded Python code blocks. From
 ReST, you can then convert to LaTeX, which should be somewhat
 importable to LyX.

 However, I haven't found a possibility yet to export ReST with embedded
 Python code blocks from Lyx.

Indeet this is a one-way conversion currently. (My suggestion was
rather to use PyLit (together with your (or my) favourite text editor)
*instead of* LyX rather than PyLit with LyX for literal programming.

 Full round-tripping between LyX and Python (or any other programming
 language) code with embedded ReST comments would be pretty close to
 The Holy Grail Of Literate Programming imho. *duck*

Adding native ReST export (and maybe import) to LyX was alredy
discussed once. Maybe some day...

Günter

Re: Documenting python code using LyX

[Guenter Milde]

On 2009-10-20, Wolfgang Keller wrote:
>> Does anybody use LyX to document python code? Any hints?

> PyLit already allows to round-trip between Python code with embedded
> ReST comments and ReST documents with embedded Python code blocks. From
> ReST, you can then convert to LaTeX, which should be somewhat
> importable to LyX.

> However, I haven't found a possibility yet to export ReST with embedded
> Python code blocks from Lyx.

Indeet this is a one-way conversion currently. (My suggestion was
rather to use PyLit (together with your (or my) favourite text editor)
*instead of* LyX rather than PyLit with LyX for literal programming.

> Full round-tripping between LyX and Python (or any other programming
> language) code with embedded ReST comments would be pretty close to
> "The Holy Grail Of Literate Programming" imho. *duck*

Adding native ReST export (and maybe import) to LyX was alredy
discussed once. Maybe some day...

Günter

Re: Documenting python code using LyX

[Wolfgang Keller]

 Does anybody use LyX to document python code? Any hints?

PyLit already allows to round-trip between Python code with embedded ReST 
comments and ReST documents with embedded Python code blocks. From ReST, you 
can then convert to LaTeX, which should be somewhat importable to LyX.

However, I haven't found a possibility yet to export ReST with embedded Python 
code blocks from Lyx.

Full round-tripping between LyX and Python (or any other programming language) 
code with embedded ReST comments would be pretty close to The Holy Grail Of 
Literate Programming imho. *duck*

Sincerely,

Wolfgang

Re: Documenting python code using LyX

[Wolfgang Keller]

 Does anybody use LyX to document python code? Any hints?

PyLit already allows to round-trip between Python code with embedded ReST 
comments and ReST documents with embedded Python code blocks. From ReST, you 
can then convert to LaTeX, which should be somewhat importable to LyX.

However, I haven't found a possibility yet to export ReST with embedded Python 
code blocks from Lyx.

Full round-tripping between LyX and Python (or any other programming language) 
code with embedded ReST comments would be pretty close to The Holy Grail Of 
Literate Programming imho. *duck*

Sincerely,

Wolfgang

Re: Documenting python code using LyX

[Wolfgang Keller]

> Does anybody use LyX to document python code? Any hints?

PyLit already allows to round-trip between Python code with embedded ReST 
comments and ReST documents with embedded Python code blocks. From ReST, you 
can then convert to LaTeX, which should be somewhat importable to LyX.

However, I haven't found a possibility yet to export ReST with embedded Python 
code blocks from Lyx.

Full round-tripping between LyX and Python (or any other programming language) 
code with embedded ReST comments would be pretty close to "The Holy Grail Of 
Literate Programming" imho. *duck*

Sincerely,

Wolfgang

Documenting python code using LyX

[Nikos Alexandris]

H LyXians!

Does anybody use LyX to document python code? Any hints? I've read about
noweb but it looks a bit more complicated than it should be... (?).

Thanks in advance, Nikos

Re: Documenting python code using LyX

[Rich Shepard]

On Wed, 14 Oct 2009, Nikos Alexandris wrote:


Does anybody use LyX to document python code? Any hints? I've read about
noweb but it looks a bit more complicated than it should be... (?).


  Why not use pydocs? That's what it's for.

Rich

Re: Documenting python code using LyX

[Manveru]

2009/10/14 Nikos Alexandris nikos.alexand...@felis.uni-freiburg.de:
 H LyXians!

 Does anybody use LyX to document python code? Any hints? I've read about
 noweb but it looks a bit more complicated than it should be... (?).

 Thanks in advance, Nikos

I am using Doxygen with doxypy extension with success. It is not ideal
at many places, but acceptable.


-- 
Manveru
jabber: manv...@manveru.pl
 gg: 1624001
   http://www.manveru.pl

Re: Documenting python code using LyX

[Nikos Alexandris]

On Wed, 2009-10-14 at 12:45 -0700, Rich Shepard wrote:
 On Wed, 14 Oct 2009, Nikos Alexandris wrote:
 
  Does anybody use LyX to document python code? Any hints? I've read about
  noweb but it looks a bit more complicated than it should be... (?).
 
Why not use pydocs? That's what it's for.
 
 Rich

Manveru, Rich,

thanks for the reply. I have in mind (most of the times) a documentation
to describe/ explain step by step what is done. I am a very beginner
with Python, not a good programmer at all and I like to spend a lot of
time to write down what each piece of code does.

I don't know if doxygen or pydoc is what I am looking for. Or is it
exactly what I need?

Thanks again, Nikos

Re: Documenting python code using LyX

[Rich Shepard]

On Wed, 14 Oct 2009, Nikos Alexandris wrote:


I don't know if doxygen or pydoc is what I am looking for. Or is it
exactly what I need?


Nikos,

  Pydocs, in specific circumstances.

  To provide multiline comments use the triple quotation mark method; for
example, This class takes the foo as input and returns the bar.
except when the situation calls for a different result.

  For single line comments use the # sign; e.g.,
# Status Bar
self.statusbar = self.CreateStatusBar(1, 0)
self.statusbar.SetStatusWidths([-1])

Rich

--
Richard B. Shepard, Ph.D.   |  IntegrityCredibility
Applied Ecosystem Services, Inc.|Innovation
http://www.appl-ecosys.com Voice: 503-667-4517  Fax: 503-667-8863

Re: Documenting python code using LyX

[Rich Shepard]

On Wed, 14 Oct 2009, Nikos Alexandris wrote:


thanks for the reply. I have in mind (most of the times) a documentation
to describe/ explain step by step what is done. I am a very beginner with
Python, not a good programmer at all and I like to spend a lot of time to
write down what each piece of code does.


Nikos,

  Let me explain more than I did in the last message. You cannot use LaTeX
to document code directly within the source, regardless of language. Each
language has conventions for embedded comments.

  Python is supposed to be quite self-documenting, but I always use
extensive comments to describe that is being done in each function, and why
I'm doing it that way. It's as much for me as for anyone else. I would not
be surprised to find that 30% of my code is comments.

  Make extensive use of the single- and multi-line comments as I wrote in
the previous message and you'll understand your code months or years from
now.

Rich

--
Richard B. Shepard, Ph.D.   |  IntegrityCredibility
Applied Ecosystem Services, Inc.|Innovation
http://www.appl-ecosys.com Voice: 503-667-4517  Fax: 503-667-8863

Re: Documenting python code using LyX

[Guenter Milde]

On 2009-10-14, Nikos Alexandris wrote:
 On Wed, 2009-10-14 at 12:45 -0700, Rich Shepard wrote:
 On Wed, 14 Oct 2009, Nikos Alexandris wrote:

  Does anybody use LyX to document python code? Any hints? I've read about
  noweb but it looks a bit more complicated than it should be... (?).

 thanks for the reply. I have in mind (most of the times) a documentation
 to describe/ explain step by step what is done. I am a very beginner
 with Python, not a good programmer at all and I like to spend a lot of
 time to write down what each piece of code does.

This sounds like literate programming:

The idea is that you do not document programs (after the fact), but
write documents that contain the programs.

and if you are looking for a simple solution, I recommend PyLit
(http://pylit.berlios.de).

Günter

Re: Documenting python code using LyX

[Nikos Alexandris]

On Wed, 2009-10-14 at 14:21 -0700, Rich Shepard wrote:
 On Wed, 14 Oct 2009, Nikos Alexandris wrote:
 
  I don't know if doxygen or pydoc is what I am looking for. Or is it
  exactly what I need?
 
 Nikos,
 
Pydocs, in specific circumstances.
 
To provide multiline comments use the triple quotation mark method; for
 example, This class takes the foo as input and returns the bar.
  except when the situation calls for a different result.
 
For single line comments use the # sign; e.g.,
   # Status Bar
   self.statusbar = self.CreateStatusBar(1, 0)
   self.statusbar.SetStatusWidths([-1])
 
 Rich

Yes, I already do that. I have more comments than code :-p. And I tried
pydoc. It works... but I am not sure this is what I need :-?

Re: Documenting python code using LyX

[Nikos Alexandris]

On Wed, 2009-10-14 at 14:25 -0700, Rich Shepard wrote:
 On Wed, 14 Oct 2009, Nikos Alexandris wrote:
 
  thanks for the reply. I have in mind (most of the times) a documentation
  to describe/ explain step by step what is done. I am a very beginner with
  Python, not a good programmer at all and I like to spend a lot of time to
  write down what each piece of code does.
 
 Nikos,
 
Let me explain more than I did in the last message. You cannot use LaTeX
 to document code directly within the source, regardless of language. Each
 language has conventions for embedded comments.
 
Python is supposed to be quite self-documenting, but I always use
 extensive comments to describe that is being done in each function, and why
 I'm doing it that way. It's as much for me as for anyone else. I would not
 be surprised to find that 30% of my code is comments.
 
Make extensive use of the single- and multi-line comments as I wrote in
 the previous message and you'll understand your code months or years from
 now.
 
 Rich
 

Right. Thanks for confirming my habit to spend time on comments. I'll
try out pylit. If it works sort of out-of-the-box, maybe it's it.

Re: Documenting python code using LyX

[Rich Shepard]

On Wed, 14 Oct 2009, Nikos Alexandris wrote:


Yes, I already do that. I have more comments than code :-p. And I tried
pydoc. It works... but I am not sure this is what I need :-?


Nikos,

  I don't know what you seek that cannot be accommodated by using the
built-in comment syntax. Perhaps you should consider using them both and see
if they help you clarify your needs.

Rich

--
Richard B. Shepard, Ph.D.   |  IntegrityCredibility
Applied Ecosystem Services, Inc.|Innovation
http://www.appl-ecosys.com Voice: 503-667-4517  Fax: 503-667-8863

Re: Documenting python code using LyX

[Nikos Alexandris]

On Wed, 2009-10-14 at 21:34 +, Guenter Milde wrote:
 On 2009-10-14, Nikos Alexandris wrote:
  On Wed, 2009-10-14 at 12:45 -0700, Rich Shepard wrote:
  On Wed, 14 Oct 2009, Nikos Alexandris wrote:
 
   Does anybody use LyX to document python code? Any hints? I've read about
   noweb but it looks a bit more complicated than it should be... (?).
 
  thanks for the reply. I have in mind (most of the times) a documentation
  to describe/ explain step by step what is done. I am a very beginner
  with Python, not a good programmer at all and I like to spend a lot of
  time to write down what each piece of code does.
 
 This sounds like literate programming:
 
 The idea is that you do not document programs (after the fact), but
 write documents that contain the programs.
 
 and if you are looking for a simple solution, I recommend PyLit
 (http://pylit.berlios.de).
 
 Günter
 

Thanks, I'll look at it.
Nice work Guenter :-)

Re: Documenting python code using LyX

[Nikos Alexandris]

On Wed, 2009-10-14 at 15:01 -0700, Rich Shepard wrote:
 On Wed, 14 Oct 2009, Nikos Alexandris wrote:
 
  Yes, I already do that. I have more comments than code :-p. And I tried
  pydoc. It works... but I am not sure this is what I need :-?
 
 Nikos,
 
I don't know what you seek that cannot be accommodated by using the
 built-in comment syntax. Perhaps you should consider using them both and see
 if they help you clarify your needs.
 
 Rich

I don't know (yet) either :-). Maybe something like... open a new LyX
document, start writing the story of my life, insert a python script in
it and have syntax highlighting (and anything else that python code
needs to be ready for copy-paste-execute) without much work.

Something like that... ?

Anyway, thanks for the replies. I think it's more clear now what the
options are.

Nikos

Documenting python code using LyX

[Nikos Alexandris]

H LyXians!

Does anybody use LyX to document python code? Any hints? I've read about
noweb but it looks a bit more complicated than it should be... (?).

Thanks in advance, Nikos

Re: Documenting python code using LyX

[Rich Shepard]

On Wed, 14 Oct 2009, Nikos Alexandris wrote:


Does anybody use LyX to document python code? Any hints? I've read about
noweb but it looks a bit more complicated than it should be... (?).


  Why not use pydocs? That's what it's for.

Rich

Re: Documenting python code using LyX

[Manveru]

2009/10/14 Nikos Alexandris nikos.alexand...@felis.uni-freiburg.de:
 H LyXians!

 Does anybody use LyX to document python code? Any hints? I've read about
 noweb but it looks a bit more complicated than it should be... (?).

 Thanks in advance, Nikos

I am using Doxygen with doxypy extension with success. It is not ideal
at many places, but acceptable.


-- 
Manveru
jabber: manv...@manveru.pl
 gg: 1624001
   http://www.manveru.pl

Re: Documenting python code using LyX

[Nikos Alexandris]

On Wed, 2009-10-14 at 12:45 -0700, Rich Shepard wrote:
 On Wed, 14 Oct 2009, Nikos Alexandris wrote:
 
  Does anybody use LyX to document python code? Any hints? I've read about
  noweb but it looks a bit more complicated than it should be... (?).
 
Why not use pydocs? That's what it's for.
 
 Rich

Manveru, Rich,

thanks for the reply. I have in mind (most of the times) a documentation
to describe/ explain step by step what is done. I am a very beginner
with Python, not a good programmer at all and I like to spend a lot of
time to write down what each piece of code does.

I don't know if doxygen or pydoc is what I am looking for. Or is it
exactly what I need?

Thanks again, Nikos

Re: Documenting python code using LyX

[Rich Shepard]

On Wed, 14 Oct 2009, Nikos Alexandris wrote:


I don't know if doxygen or pydoc is what I am looking for. Or is it
exactly what I need?


Nikos,

  Pydocs, in specific circumstances.

  To provide multiline comments use the triple quotation mark method; for
example, This class takes the foo as input and returns the bar.
except when the situation calls for a different result.

  For single line comments use the # sign; e.g.,
# Status Bar
self.statusbar = self.CreateStatusBar(1, 0)
self.statusbar.SetStatusWidths([-1])

Rich

--
Richard B. Shepard, Ph.D.   |  IntegrityCredibility
Applied Ecosystem Services, Inc.|Innovation
http://www.appl-ecosys.com Voice: 503-667-4517  Fax: 503-667-8863

Re: Documenting python code using LyX

[Rich Shepard]

On Wed, 14 Oct 2009, Nikos Alexandris wrote:


thanks for the reply. I have in mind (most of the times) a documentation
to describe/ explain step by step what is done. I am a very beginner with
Python, not a good programmer at all and I like to spend a lot of time to
write down what each piece of code does.


Nikos,

  Let me explain more than I did in the last message. You cannot use LaTeX
to document code directly within the source, regardless of language. Each
language has conventions for embedded comments.

  Python is supposed to be quite self-documenting, but I always use
extensive comments to describe that is being done in each function, and why
I'm doing it that way. It's as much for me as for anyone else. I would not
be surprised to find that 30% of my code is comments.

  Make extensive use of the single- and multi-line comments as I wrote in
the previous message and you'll understand your code months or years from
now.

Rich

--
Richard B. Shepard, Ph.D.   |  IntegrityCredibility
Applied Ecosystem Services, Inc.|Innovation
http://www.appl-ecosys.com Voice: 503-667-4517  Fax: 503-667-8863

Re: Documenting python code using LyX

[Guenter Milde]

On 2009-10-14, Nikos Alexandris wrote:
 On Wed, 2009-10-14 at 12:45 -0700, Rich Shepard wrote:
 On Wed, 14 Oct 2009, Nikos Alexandris wrote:

  Does anybody use LyX to document python code? Any hints? I've read about
  noweb but it looks a bit more complicated than it should be... (?).

 thanks for the reply. I have in mind (most of the times) a documentation
 to describe/ explain step by step what is done. I am a very beginner
 with Python, not a good programmer at all and I like to spend a lot of
 time to write down what each piece of code does.

This sounds like literate programming:

The idea is that you do not document programs (after the fact), but
write documents that contain the programs.

and if you are looking for a simple solution, I recommend PyLit
(http://pylit.berlios.de).

Günter

Re: Documenting python code using LyX

[Nikos Alexandris]

On Wed, 2009-10-14 at 14:21 -0700, Rich Shepard wrote:
 On Wed, 14 Oct 2009, Nikos Alexandris wrote:
 
  I don't know if doxygen or pydoc is what I am looking for. Or is it
  exactly what I need?
 
 Nikos,
 
Pydocs, in specific circumstances.
 
To provide multiline comments use the triple quotation mark method; for
 example, This class takes the foo as input and returns the bar.
  except when the situation calls for a different result.
 
For single line comments use the # sign; e.g.,
   # Status Bar
   self.statusbar = self.CreateStatusBar(1, 0)
   self.statusbar.SetStatusWidths([-1])
 
 Rich

Yes, I already do that. I have more comments than code :-p. And I tried
pydoc. It works... but I am not sure this is what I need :-?

Re: Documenting python code using LyX

[Nikos Alexandris]

On Wed, 2009-10-14 at 14:25 -0700, Rich Shepard wrote:
 On Wed, 14 Oct 2009, Nikos Alexandris wrote:
 
  thanks for the reply. I have in mind (most of the times) a documentation
  to describe/ explain step by step what is done. I am a very beginner with
  Python, not a good programmer at all and I like to spend a lot of time to
  write down what each piece of code does.
 
 Nikos,
 
Let me explain more than I did in the last message. You cannot use LaTeX
 to document code directly within the source, regardless of language. Each
 language has conventions for embedded comments.
 
Python is supposed to be quite self-documenting, but I always use
 extensive comments to describe that is being done in each function, and why
 I'm doing it that way. It's as much for me as for anyone else. I would not
 be surprised to find that 30% of my code is comments.
 
Make extensive use of the single- and multi-line comments as I wrote in
 the previous message and you'll understand your code months or years from
 now.
 
 Rich
 

Right. Thanks for confirming my habit to spend time on comments. I'll
try out pylit. If it works sort of out-of-the-box, maybe it's it.

Re: Documenting python code using LyX

[Rich Shepard]

On Wed, 14 Oct 2009, Nikos Alexandris wrote:


Yes, I already do that. I have more comments than code :-p. And I tried
pydoc. It works... but I am not sure this is what I need :-?


Nikos,

  I don't know what you seek that cannot be accommodated by using the
built-in comment syntax. Perhaps you should consider using them both and see
if they help you clarify your needs.

Rich

--
Richard B. Shepard, Ph.D.   |  IntegrityCredibility
Applied Ecosystem Services, Inc.|Innovation
http://www.appl-ecosys.com Voice: 503-667-4517  Fax: 503-667-8863

Re: Documenting python code using LyX

[Nikos Alexandris]

On Wed, 2009-10-14 at 21:34 +, Guenter Milde wrote:
 On 2009-10-14, Nikos Alexandris wrote:
  On Wed, 2009-10-14 at 12:45 -0700, Rich Shepard wrote:
  On Wed, 14 Oct 2009, Nikos Alexandris wrote:
 
   Does anybody use LyX to document python code? Any hints? I've read about
   noweb but it looks a bit more complicated than it should be... (?).
 
  thanks for the reply. I have in mind (most of the times) a documentation
  to describe/ explain step by step what is done. I am a very beginner
  with Python, not a good programmer at all and I like to spend a lot of
  time to write down what each piece of code does.
 
 This sounds like literate programming:
 
 The idea is that you do not document programs (after the fact), but
 write documents that contain the programs.
 
 and if you are looking for a simple solution, I recommend PyLit
 (http://pylit.berlios.de).
 
 Günter
 

Thanks, I'll look at it.
Nice work Guenter :-)

Re: Documenting python code using LyX

[Nikos Alexandris]

On Wed, 2009-10-14 at 15:01 -0700, Rich Shepard wrote:
 On Wed, 14 Oct 2009, Nikos Alexandris wrote:
 
  Yes, I already do that. I have more comments than code :-p. And I tried
  pydoc. It works... but I am not sure this is what I need :-?
 
 Nikos,
 
I don't know what you seek that cannot be accommodated by using the
 built-in comment syntax. Perhaps you should consider using them both and see
 if they help you clarify your needs.
 
 Rich

I don't know (yet) either :-). Maybe something like... open a new LyX
document, start writing the story of my life, insert a python script in
it and have syntax highlighting (and anything else that python code
needs to be ready for copy-paste-execute) without much work.

Something like that... ?

Anyway, thanks for the replies. I think it's more clear now what the
options are.

Nikos

Documenting python code using LyX

[Nikos Alexandris]

H LyXians!

Does anybody use LyX to document python code? Any hints? I've read about
noweb but it looks a bit more complicated than it should be... (?).

Thanks in advance, Nikos

Re: Documenting python code using LyX

[Rich Shepard]

On Wed, 14 Oct 2009, Nikos Alexandris wrote:


Does anybody use LyX to document python code? Any hints? I've read about
noweb but it looks a bit more complicated than it should be... (?).


  Why not use pydocs? That's what it's for.

Rich

Re: Documenting python code using LyX

[Manveru]

2009/10/14 Nikos Alexandris :
> H LyXians!
>
> Does anybody use LyX to document python code? Any hints? I've read about
> noweb but it looks a bit more complicated than it should be... (?).
>
> Thanks in advance, Nikos

I am using Doxygen with doxypy extension with success. It is not ideal
at many places, but acceptable.


-- 
Manveru
jabber: manv...@manveru.pl
 gg: 1624001
   http://www.manveru.pl

Re: Documenting python code using LyX

[Nikos Alexandris]

On Wed, 2009-10-14 at 12:45 -0700, Rich Shepard wrote:
> On Wed, 14 Oct 2009, Nikos Alexandris wrote:
> 
> > Does anybody use LyX to document python code? Any hints? I've read about
> > noweb but it looks a bit more complicated than it should be... (?).
> 
>Why not use pydocs? That's what it's for.
> 
> Rich

Manveru, Rich,

thanks for the reply. I have in mind (most of the times) a documentation
to describe/ explain step by step what is done. I am a very beginner
with Python, not a good programmer at all and I like to spend a lot of
time to write down what each piece of code does.

I don't know if doxygen or pydoc is what I am looking for. Or is it
exactly what I need?

Thanks again, Nikos

Re: Documenting python code using LyX

[Rich Shepard]

On Wed, 14 Oct 2009, Nikos Alexandris wrote:


I don't know if doxygen or pydoc is what I am looking for. Or is it
exactly what I need?


Nikos,

  Pydocs, in specific circumstances.

  To provide multiline comments use the triple quotation mark method; for
example, """This class takes the foo as input and returns the bar.
except when the situation calls for a different result."""

  For single line comments use the # sign; e.g.,
# Status Bar
self.statusbar = self.CreateStatusBar(1, 0)
self.statusbar.SetStatusWidths([-1])

Rich

--
Richard B. Shepard, Ph.D.   |  IntegrityCredibility
Applied Ecosystem Services, Inc.|Innovation
 Voice: 503-667-4517  Fax: 503-667-8863

Re: Documenting python code using LyX

[Rich Shepard]

On Wed, 14 Oct 2009, Nikos Alexandris wrote:


thanks for the reply. I have in mind (most of the times) a documentation
to describe/ explain step by step what is done. I am a very beginner with
Python, not a good programmer at all and I like to spend a lot of time to
write down what each piece of code does.


Nikos,

  Let me explain more than I did in the last message. You cannot use LaTeX
to document code directly within the source, regardless of language. Each
language has conventions for embedded comments.

  Python is supposed to be quite self-documenting, but I always use
extensive comments to describe that is being done in each function, and why
I'm doing it that way. It's as much for me as for anyone else. I would not
be surprised to find that 30% of my code is comments.

  Make extensive use of the single- and multi-line comments as I wrote in
the previous message and you'll understand your code months or years from
now.

Rich

--
Richard B. Shepard, Ph.D.   |  IntegrityCredibility
Applied Ecosystem Services, Inc.|Innovation
 Voice: 503-667-4517  Fax: 503-667-8863

Re: Documenting python code using LyX

[Guenter Milde]

On 2009-10-14, Nikos Alexandris wrote:
> On Wed, 2009-10-14 at 12:45 -0700, Rich Shepard wrote:
>> On Wed, 14 Oct 2009, Nikos Alexandris wrote:

>> > Does anybody use LyX to document python code? Any hints? I've read about
>> > noweb but it looks a bit more complicated than it should be... (?).

> thanks for the reply. I have in mind (most of the times) a documentation
> to describe/ explain step by step what is done. I am a very beginner
> with Python, not a good programmer at all and I like to spend a lot of
> time to write down what each piece of code does.

This sounds like "literate programming":

The idea is that you do not document programs (after the fact), but
write documents that contain the programs.

and if you are looking for a simple solution, I recommend PyLit
(http://pylit.berlios.de).

Günter

Re: Documenting python code using LyX

[Nikos Alexandris]

On Wed, 2009-10-14 at 14:21 -0700, Rich Shepard wrote:
> On Wed, 14 Oct 2009, Nikos Alexandris wrote:
> 
> > I don't know if doxygen or pydoc is what I am looking for. Or is it
> > exactly what I need?
> 
> Nikos,
> 
>Pydocs, in specific circumstances.
> 
>To provide multiline comments use the triple quotation mark method; for
> example, """This class takes the foo as input and returns the bar.
>  except when the situation calls for a different result."""
> 
>For single line comments use the # sign; e.g.,
>   # Status Bar
>   self.statusbar = self.CreateStatusBar(1, 0)
>   self.statusbar.SetStatusWidths([-1])
> 
> Rich

Yes, I already do that. I have more comments than code :-p. And I tried
pydoc. It works... but I am not sure this is what I need :-?

Re: Documenting python code using LyX

[Nikos Alexandris]

On Wed, 2009-10-14 at 14:25 -0700, Rich Shepard wrote:
> On Wed, 14 Oct 2009, Nikos Alexandris wrote:
> 
> > thanks for the reply. I have in mind (most of the times) a documentation
> > to describe/ explain step by step what is done. I am a very beginner with
> > Python, not a good programmer at all and I like to spend a lot of time to
> > write down what each piece of code does.
> 
> Nikos,
> 
>Let me explain more than I did in the last message. You cannot use LaTeX
> to document code directly within the source, regardless of language. Each
> language has conventions for embedded comments.
> 
>Python is supposed to be quite self-documenting, but I always use
> extensive comments to describe that is being done in each function, and why
> I'm doing it that way. It's as much for me as for anyone else. I would not
> be surprised to find that 30% of my code is comments.
> 
>Make extensive use of the single- and multi-line comments as I wrote in
> the previous message and you'll understand your code months or years from
> now.
> 
> Rich
> 

Right. Thanks for confirming my habit to spend time on comments. I'll
try out pylit. If it works sort of out-of-the-box, maybe it's it.

Re: Documenting python code using LyX

[Rich Shepard]

On Wed, 14 Oct 2009, Nikos Alexandris wrote:


Yes, I already do that. I have more comments than code :-p. And I tried
pydoc. It works... but I am not sure this is what I need :-?


Nikos,

  I don't know what you seek that cannot be accommodated by using the
built-in comment syntax. Perhaps you should consider using them both and see
if they help you clarify your needs.

Rich

--
Richard B. Shepard, Ph.D.   |  IntegrityCredibility
Applied Ecosystem Services, Inc.|Innovation
 Voice: 503-667-4517  Fax: 503-667-8863

Re: Documenting python code using LyX

[Nikos Alexandris]

On Wed, 2009-10-14 at 21:34 +, Guenter Milde wrote:
> On 2009-10-14, Nikos Alexandris wrote:
> > On Wed, 2009-10-14 at 12:45 -0700, Rich Shepard wrote:
> >> On Wed, 14 Oct 2009, Nikos Alexandris wrote:
> 
> >> > Does anybody use LyX to document python code? Any hints? I've read about
> >> > noweb but it looks a bit more complicated than it should be... (?).
> 
> > thanks for the reply. I have in mind (most of the times) a documentation
> > to describe/ explain step by step what is done. I am a very beginner
> > with Python, not a good programmer at all and I like to spend a lot of
> > time to write down what each piece of code does.
> 
> This sounds like "literate programming":
> 
> The idea is that you do not document programs (after the fact), but
> write documents that contain the programs.
> 
> and if you are looking for a simple solution, I recommend PyLit
> (http://pylit.berlios.de).
> 
> Günter
> 

Thanks, I'll look at it.
Nice work Guenter :-)

Re: Documenting python code using LyX

[Nikos Alexandris]

On Wed, 2009-10-14 at 15:01 -0700, Rich Shepard wrote:
> On Wed, 14 Oct 2009, Nikos Alexandris wrote:
> 
> > Yes, I already do that. I have more comments than code :-p. And I tried
> > pydoc. It works... but I am not sure this is what I need :-?
> 
> Nikos,
> 
>I don't know what you seek that cannot be accommodated by using the
> built-in comment syntax. Perhaps you should consider using them both and see
> if they help you clarify your needs.
> 
> Rich

I don't know (yet) either :-). Maybe something like... open a new LyX
document, start writing the story of my life, insert a python script in
it and have syntax highlighting (and anything else that python code
needs to be ready for copy-paste-execute) without much work.

Something like that... ?

Anyway, thanks for the replies. I think it's more clear now what the
options are.

Nikos