Documentation examples needed

[Stuart D. Gathman]

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 Cole]

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

 

[Raymond Hettinger]

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> 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.

 

[Dave Kuhlman]

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]

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