[Baypiggies] Help: I'm being thick

[Glen Jarvis]

hehehe.. sure! If I can get past this, I can give a talk on it. I  
think we're pretty booked up until around June. So, that gives me  
plenty of time to discuss documentation, restructured text, and  
Sphinx. I know JJ will have a few things to say about it too =)

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

On Feb 11, 2009, at 7:36 PM, jim wrote:

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