Documentation examples needed
 

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 <stuart@bmsi.com>
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.

Re: Documentation examples needed
 

>>>>> "Stuart" == Stuart D Gathman <stuart@bmsi.com> 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

Re: Documentation examples needed
 

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" <stuart@bmsi.com> 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 <stuart@bmsi.com>
> 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.

Re: Documentation examples needed
 

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 <stuart@bmsi.com>
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.

Re: Documentation examples needed
 

Michele Simionato wrote:

> "Stuart D. Gathman" <stuart@bmsi.com> 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
dkuhlman@rexx.com

Re: Documentation examples needed
 

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
dkuhlman@rexx.com