Routes documentation

[Mike Orr]

I've got the Routes documentation updated in Routes-dev
(http://bitbucket/bbangert/routes). It contains the new manual, a
TODO, and changes to the Sphinx home page. I don't know what to do
about the following issues:

- It assumes Routes 1.11 will be released simultaneously with it.

- I'm not quite satisfied with the home page. It looks too generic
Sphinx. The content should be shorter so all the navigation links fit
on the first screen. Can anybody make a little Routes logo to liven
it up?

- The generated module docs are incomplete (i.e., completely empty).
I don't know how to pull in the docstrings.

- The "Indices and Tables" section in the documentation contents page
is redundant with the glossary link, modules link, and the modules
link. I would delete the section.

- The sidebar on the documentation contents page is too wordy.

- The sidebar in the manual should only show sections, not subsections.

- The sidebar on the TODO page should be blank except for the search form.

--
Mike Orr <slugg...@gmail.com>

[Mike Orr]

So now I'm trying to generate the module docs to WebHelpers and am
running into the same problem: there's a link to the top-level module
but its page is blank. Currently I have:

.. automodule:: webhelpers

So I looked in the Beaker package, and it has an
autoclass/autofunction for every single item. I can't do that for the
tons of items in WebHelpers and keep it up to date. Would it be
better to use Epydoc which can generate a whole package at once? Is
there a way to plug Epydoc documentation into Sphinx?

--
Mike Orr <slugg...@gmail.com>

[Mike Orr]

And how to you arrange for Sphinx to import the package it's
documenting if it's in a sibling directory or parent directory of the
docs directory? Righit now I think it's documenting the webhelpers in
my virtualenv, but what I really want it to do is to document the
package in the source.

--
Mike Orr <slugg...@gmail.com>

[Gael Pasgrimaud]

Hi,

I guess you can use autogen:
http://sphinx.pocoo.org/ext/autosummary.html#sphinx-autogen-generate-autodoc-stub-pages

I've never used it. It's new in the last Sphinx version AFAIK.

--
Gael

[Gael Pasgrimaud]

On Thu, Sep 17, 2009 at 8:48 AM, Mike Orr <slugg...@gmail.com> wrote:
>
> And how to you arrange for Sphinx to import the package it's
> documenting if it's in a sibling directory or parent directory of the
> docs directory?  Righit now I think it's documenting the webhelpers in
> my virtualenv, but what I really want it to do is to document the
> package in the source.
>

I use buildout. Add a buildout.cfg at the root of your package:

[buildout]
newest = false
parts = eggs
develop = .

[eggs]
recipe = zc.recipe.egg
eggs =
WebHelpers
Sphinx
nose

Run buildout. Then you are able to use buildout's binaries to run
nose/sphinx. You just need to change Sphinx's Makefile so he use
../bin/sphinx-build

Have a look at this package as a full example (with bootstrap.py /
.hgignore): http://bitbucket.org/gawel/configobject/src/

--
Gael

> --
> Mike Orr <slugg...@gmail.com>
>
> >
>