[Baypiggies] Help: I'm being thick

[jim]

   i say let's help glen develop a baypiggies 
talk on restructured text for pythonistas. 



On Wed, 2009-02-11 at 19:07 -0800, Glen Jarvis wrote:
> 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
> 
> _______________________________________________
> Baypiggies mailing list
> Baypiggies at python.org
> To change your subscription options or unsubscribe:
> http://mail.python.org/mailman/listinfo/baypiggies