Velocity Reviews - Computer Hardware Reviews

Velocity Reviews > Newsgroups > Programming > Python > Documentation examples needed

Reply
Thread Tools

Documentation examples needed

 
 
Stuart D. Gathman
Guest
Posts: n/a
 
      07-17-2003
I am still wanting to produce Python standard format documentation for
Python extensions I have written. I have looked at the docs that come
with Python itself, but I am new to Latex, and don't know how to add the
document classes and styles from texinput for a new project.

Is there a small project with documentation in the Python standard that I
can use as an example?

--
Stuart D. Gathman <(E-Mail Removed)>
Business Management Systems Inc. Phone: 703 591-0911 Fax: 703 591-6154
"Confutatis maledictis, flamis acribus addictis" - background song for
a Microsoft sponsored "Where do you want to go from here?" commercial.
 
Reply With Quote
 
 
 
 
Dave Cole
Guest
Posts: n/a
 
      07-17-2003
>>>>> "Stuart" == Stuart D Gathman <(E-Mail Removed)> writes:

Stuart> I am still wanting to produce Python standard format
Stuart> documentation for Python extensions I have written. I have
Stuart> looked at the docs that come with Python itself, but I am new
Stuart> to Latex, and don't know how to add the document classes and
Stuart> styles from texinput for a new project.

Stuart> Is there a small project with documentation in the Python
Stuart> standard that I can use as an example?

We have some:

http://www.object-craft.com.au/projects/albatross/
http://www.object-craft.com.au/projects/sybase/sybase/

- Dave

--
http://www.object-craft.com.au
 
Reply With Quote
 
 
 
 
Raymond Hettinger
Guest
Posts: n/a
 
      07-17-2003
Hi Stuart,

The simplest way to get started with Python standard LaTeX markup
is to cut-and-paste from existing TeX files. Then follow-up with a
script to perform basic checks: see the current CVS for

Tools/scripts/texcheck.py

It will check for valid TeX markup, balanced delimiters, style warnings,
and common markup errors (for example, confusing forward and
backward slashes).

A better way to get started is to actually read the Documenting Python
section. In the end, you'll save more time and learn more than
the try-it and see if it works method.


Raymond Hettinger



"Stuart D. Gathman" <(E-Mail Removed)> wrote in message
news:aUnRa.16108$o54.11296@lakeread05...
> I am still wanting to produce Python standard format documentation for
> Python extensions I have written. I have looked at the docs that come
> with Python itself, but I am new to Latex, and don't know how to add the
> document classes and styles from texinput for a new project.
>
> Is there a small project with documentation in the Python standard that I
> can use as an example?
>
> --
> Stuart D. Gathman <(E-Mail Removed)>
> Business Management Systems Inc. Phone: 703 591-0911 Fax: 703 591-6154
> "Confutatis maledictis, flamis acribus addictis" - background song for
> a Microsoft sponsored "Where do you want to go from here?" commercial.



 
Reply With Quote
 
Stuart D. Gathman
Guest
Posts: n/a
 
      07-17-2003
On Thu, 17 Jul 2003 00:44:44 -0400, Dave Cole wrote:

> Stuart> Is there a small project with documentation in the Python
> Stuart> standard that I can use as an example?
>
> We have some:
>
> http://www.object-craft.com.au/projects/albatross/
> http://www.object-craft.com.au/projects/sybase/sybase/


Thank you. Your Makefile is much less confusing than the one that comes
with Python! It also points out a shortcoming of the RPM packaging. The
python2-devel package includes everything you need to compile python
extension modules, but does not include what is needed to "compile"
python documentation! Are third party module writers not supposed to
document anything? It looks like I'll have to download the Python
sources and create my own RPMs.

Presumably, I do not need *everything* in the Doc directory to compile my
own docs. Probably just the tools directory, and maybe texinputs and
templates. Is the list of what is needed for 3rd party docs documented
somewhere? I can create a python2-doc rpm for it.

--
Stuart D. Gathman <(E-Mail Removed)>
Business Management Systems Inc. Phone: 703 591-0911 Fax: 703 591-6154
"Confutatis maledictis, flamis acribus addictis" - background song for
a Microsoft sponsored "Where do you want to go from here?" commercial.
 
Reply With Quote
 
Dave Kuhlman
Guest
Posts: n/a
 
      07-19-2003
Michele Simionato wrote:

> "Stuart D. Gathman" <(E-Mail Removed)> wrote in message
> news:<aUnRa.16108$o54.11296@lakeread05>...
>> I am still wanting to produce Python standard format
>> documentation for
>> Python extensions I have written. I have looked at the docs that
>> come with Python itself, but I am new to Latex, and don't know
>> how to add the document classes and styles from texinput for a
>> new project.
>>
>> Is there a small project with documentation in the Python
>> standard that I can use as an example?

>
> Dave Kuhlman reported on the docutils mailing list that it was
> working on a docutils writer to produce standard Python
> documentation.
>
> http://www.rexx.com/~dkuhlman/#docutilsdocpy


Right. This extension to Docutils makes it easy to generate LaTeX
files for input to the Python LaTeX documentation system. This
method enables you to write reStructuredText (reST) documents,
which have *minimal* mark-up, then translate them into LaTeX
documents. Use this and you may be able to avoid learning LaTeX,
which might *not* be a good thing. Also be aware, that this
method lacks features that are supported by LaTeX mark-up
described in "Documenting Python".

Here are updated links:

http://www.rexx.com/~dkuhlman/#docutils_pythonlatex
http://www.rexx.com/~dkuhlman/rstpythonlatex_intro.html
http://www.rexx.com/~dkuhlman/rstpythonlatex-1.0b.zip

I've also written a document about how to set yourself up for
processing documents with the Python LaTeX documentation system
and the above mentioned reST-to-Python-LaTeX translator..
You can find it here:

http://www.rexx.com/~dkuhlman/#pythonlatexsetup
http://www.rexx.com/~dkuhlman/pythonlatexsetup.html
http://www.rexx.com/~dkuhlman/pythonlatexsetup.zip

Comments are welcome.

- Dave

--
Dave Kuhlman
http://www.rexx.com/~dkuhlman
http://www.velocityreviews.com/forums/(E-Mail Removed)
 
Reply With Quote
 
Dave Kuhlman
Guest
Posts: n/a
 
      07-19-2003
Stuart D. Gathman wrote:

> On Thu, 17 Jul 2003 00:44:44 -0400, Dave Cole wrote:
>
>> Stuart> Is there a small project with documentation in the Python
>> Stuart> standard that I can use as an example?
>>
>> We have some:
>>
>> http://www.object-craft.com.au/projects/albatross/
>> http://www.object-craft.com.au/projects/sybase/sybase/

>
> Thank you. Your Makefile is much less confusing than the one that
> comes
> with Python! It also points out a shortcoming of the RPM
> packaging. The python2-devel package includes everything you need
> to compile python extension modules, but does not include what is
> needed to "compile"
> python documentation! Are third party module writers not supposed
> to document anything? It looks like I'll have to download the
> Python sources and create my own RPMs.
>
> Presumably, I do not need *everything* in the Doc directory to
> compile my
> own docs. Probably just the tools directory, and maybe texinputs
> and
> templates. Is the list of what is needed for 3rd party docs
> documented
> somewhere?


The file Doc/README (in the Python source code distribution) has
some of this information. You will have to scan down a ways for
it, though.

- Dave

--
Dave Kuhlman
http://www.rexx.com/~dkuhlman
(E-Mail Removed)
 
Reply With Quote
 
 
 
Reply

Thread Tools

Posting Rules
You may not post new threads
You may not post replies
You may not post attachments
You may not edit your posts

BB code is On
Smilies are On
[IMG] code is On
HTML code is Off
Trackbacks are On
Pingbacks are On
Refbacks are Off


Similar Threads
Thread Thread Starter Forum Replies Last Post
.Net Tips, C# Tips : Create a well formed URI using UriBuilder classwith C# Examples and VB.Net Examples jayeshsorathia@gmail.com ASP .Net 1 07-31-2012 01:03 AM
RESUME EXAMPLES INFORMATION / CV EXAMPLES NOW AVAILABLE THROUGHRESUMEWRITERGUIDE.COM rawebadvert3 Computer Support 0 03-23-2008 04:19 AM
COVER LETTERS RESUME EXAMPLES AND CV EXAMPLES AVAILABLE CURRICULUM VITAE rawebadvert3 Computer Support 0 08-21-2007 03:07 AM
COVER LETTERS RESUME EXAMPLES AND CV EXAMPLES AVAILABLE rawebadvert3 Computer Support 0 05-25-2007 04:18 AM



Advertisments