Documentation examples needed

Discussion in 'Python' started by Stuart D. Gathman, Jul 17, 2003.

  1. 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 <>
    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.
     
    Stuart D. Gathman, Jul 17, 2003
    #1
    1. Advertising

  2. Stuart D. Gathman

    Dave Cole Guest

    >>>>> "Stuart" == Stuart D Gathman <> 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
     
    Dave Cole, Jul 17, 2003
    #2
    1. Advertising

  3. 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" <> 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 <>
    > 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.
     
    Raymond Hettinger, Jul 17, 2003
    #3
  4. 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 <>
    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.
     
    Stuart D. Gathman, Jul 17, 2003
    #4
  5. Stuart D. Gathman

    Dave Kuhlman Guest

    Michele Simionato wrote:

    > "Stuart D. Gathman" <> 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
     
    Dave Kuhlman, Jul 19, 2003
    #5
  6. Stuart D. Gathman

    Dave Kuhlman Guest

    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
     
    Dave Kuhlman, Jul 19, 2003
    #6
    1. Advertising

Want to reply to this thread or ask your own question?

It takes just 2 minutes to sign up (and it's free!). Just click the sign up button to choose a username and then you can ask your own questions on the forum.
Similar Threads
  1. Boris Boutillier
    Replies:
    0
    Views:
    988
    Boris Boutillier
    Jun 15, 2004
  2. Efrat Regev
    Replies:
    1
    Views:
    604
    Bill Mill
    Mar 24, 2007
  3. Harishankar
    Replies:
    4
    Views:
    1,959
    Harishankar
    Mar 27, 2010
  4. Mark Wilson
    Replies:
    1
    Views:
    136
    Takashi & Kayoko Sano
    Sep 4, 2003
  5. benny
    Replies:
    12
    Views:
    269
    benny
    Dec 12, 2004
Loading...

Share This Page