[Baypiggies] Help: I'm being thick

[Glen Jarvis]

I'm very confused about something so simple.

I'm learning to use Sphinx. I want to make certain I use the  
reStructured Text properly in my project documentation, so I thought  
I'd install Sphinx and actually look at my documentation to verify it  
looks they way I thin it should.

I can't get my Sphinx project to build the files I've added. I'm  
certain it's user error, but I can't find it. I've read the  
documentation several times -- enough to be completely confused at  
something simple.

My core confusion comes from how I have structured my Django project.  
My project has a similar structure to this:

-- myproject
+ settings.py and other misc files
+---- grants
       +---- models.py

I've gotten a good part of the project working, but I can't get the  
documentation piece to work.

I've used sphinx-quickstart, and chose a structure like this:

-- myproject
+ settings.py and other misc files
+---- grants
       +---- models.py
+---- docs
       +---- build
       |---- Makefile
       + source
       +---- models.py
       +---- index.rst
       +---- conf.py

But, I'm confused. It seems that sphinx-quickstart needs files to be  
located in the docs/source directory. I can rebuild it so that this is  
the case, but it's some work to rearrange my subversion repository.  
Before I do something so extreme, I'm trying to test my understanding.

Currently, my index.rst file looks similar to this:

Contents:

.. toctree::
     :maxdepth: 2

     models.py



I've copied certain files into the source directory to see if I can  
generate documentation. But, even then, I see the following:

 > make html
Sphinx v0.5.1, building html
WARNING: /home/gjarvis/trunk/docs/source/index.rst:10: (WARNING/2)  
toctree references unknown document u'models.py'

Before I tried these tests, I had created a symbolic ilnk from  
myproject/docs/source/models.py to myproject.grants/models.py, and  
that seemed to generate the file... but, I've seen results that seem  
contradictory enough I'm completely confused...


Can anyone point me to some clear documentation, or give me some  
pointers on what my misunderstanding is about? Also, which of the two  
'structures' am I to use with Sphinx.


Thanks in advance for any help you can give.


Cheers,


Glen
--
415-680-3964
glen at glenjarvis.com
http://www.glenjarvis.com

"You must be the change you wish to see in the world." -M. Gandhi

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/baypiggies/attachments/20090211/25c148b2/attachment.htm>