Glen,<br><br>We use Sphinx in the Pympler project. The file structure under the doc directory is like the one you show above. The key files to get right are conf.py and index.rst in the doc/source directory. For examples, see<br>
<br><<a href="http://code.google.com/p/pympler/source/browse/trunk/doc/source/conf.py">http://code.google.com/p/pympler/source/browse/trunk/doc/source/conf.py</a>><br><<a href="http://code.google.com/p/pympler/source/browse/trunk/doc/source/index.rst">http://code.google.com/p/pympler/source/browse/trunk/doc/source/index.rst</a>><div>
<br>The file or module names mentioned inside index.rst have no extensions: all names refer to .rst files.<br><br>Hope this helps,<br><br>/Jean Brouwers<br><br>PS) Just FYI, we made 3 changes to run Sphinx in a pympler-dev environment.<div>
<br></div><div>- The Makefile is not used and has been removed.</div><div><br></div><div>- Sphinx is run using the sphinx.py script in the tools directory</div><div><<a href="http://code.google.com/p/pympler/source/browse/trunk/tools/">http://code.google.com/p/pympler/source/browse/trunk/tools/</a>>.<br>
<br>- To build the docs, etc. we use the run.py script in the top level directory<br><<a href="http://code.google.com/p/pympler/source/browse/#svn/trunk">http://code.google.com/p/pympler/source/browse/#svn/trunk</a>>, see the run_sphinx function in there. Options --doctest, --html, --latex and --linkcheck end up running Sphinx.<br>
<br><span class="Apple-style-span" style="font-family: 'courier new', monospace;">% ./run.py -h<br>Usage: run.py <options> [<args> ...]<br><br> e.g. run.py --clean<br> run.py --dist [--upload] [gztar] [zip]<br>
run.py --doctest<br> run.py --html [--keep]<br> run.py --latex [--paper=letter|a4]<br> run.py --linkcheck<br> run.py --pychecker [--OKd] [pympler | pympler/module] ...<br> run.py --test [test | test/module | test/module/test_suite.py ...]<br>
<br>Options:<br> -h, --help show this help message and exit<br> -a, --all run all tests and create all documentation<br> -c, --clean remove bytecode files from source and test directories<br> -d, --dist create the distributions<br>
-D, --doctest run the documentation tests<br> -H, --html create the HTML documentation<br> -k, --keep keep documentation in the doc directory<br> -L, --latex create the LaTeX (PDF) documentation<br>
--paper=PAPER select LaTeX paper size (letter)<br> -i, --linkcheck check the documentation links<br> -p, --pychecker run static code analyzer PyChecker<br> --OKd include PyChecker warnings OKd in source<br>
-t, --test run all or specific unit tests<br> --upload upload distributions to the Python Cheese Shop<br> -V V, --verbose=V set verbosity level (1)<br></span><br><br><br>On Wed, Feb 11, 2009 at 7:07 PM, Glen Jarvis <<a href="mailto:glen@glenjarvis.com">glen@glenjarvis.com</a>> wrote:<br>
> I'm very confused about something so simple.<br>> I'm learning to use Sphinx. I want to make certain I use the reStructured<br>> Text properly in my project documentation, so I thought I'd install Sphinx<br>
> and actually look at my documentation to verify it looks they way I thin it<br>> should.<br>> I can't get my Sphinx project to build the files I've added. I'm certain<br>> it's user error, but I can't find it. I've read the documentation several<br>
> times -- enough to be completely confused at something simple.<br>> My core confusion comes from how I have structured my Django project. My<br>> project has a similar structure to this:<br>> -- myproject<br>
> + settings.py and other misc files<br>> +---- grants<br>> +---- models.py<br>> I've gotten a good part of the project working, but I can't get the<br>> documentation piece to work.<br>> I've used sphinx-quickstart, and chose a structure like this:<br>
> -- myproject<br>> + settings.py and other misc files<br>> +---- grants<br>> +---- models.py<br>> +---- docs<br>> +---- build<br>> |---- Makefile<br>> + source<br>> +---- models.py<br>
> +---- index.rst<br>> +---- conf.py<br>> But, I'm confused. It seems that sphinx-quickstart needs files to be located<br>> in the docs/source directory. I can rebuild it so that this is the case, but<br>
> it's some work to rearrange my subversion repository. Before I do something<br>> so extreme, I'm trying to test my understanding. <br>> Currently, my index.rst file looks similar to this:<br>> Contents:<br>
> .. toctree::<br>> :maxdepth: 2<br>> models.py<br>><br>><br>> I've copied certain files into the source directory to see if I can generate<br>> documentation. But, even then, I see the following:<br>
>> make html<br>> Sphinx v0.5.1, building html<br>> WARNING: /home/gjarvis/trunk/docs/source/index.rst:10: (WARNING/2) toctree<br>> references unknown document u'models.py'<br>> Before I tried these tests, I had created a symbolic ilnk from<br>
> myproject/docs/source/models.py to myproject.grants/models.py, and that<br>> seemed to generate the file... but, I've seen results that seem<br>> contradictory enough I'm completely confused...<br>><br>
> Can anyone point me to some clear documentation, or give me some pointers on<br>> what my misunderstanding is about? Also, which of the two 'structures' am I<br>> to use with Sphinx.<br>><br>> Thanks in advance for any help you can give.<br>
><br>> Cheers,<br>><br>> Glen<br>> --<br>> 415-680-3964<br>> <a href="mailto:glen@glenjarvis.com">glen@glenjarvis.com</a><br>> <a href="http://www.glenjarvis.com">http://www.glenjarvis.com</a><br>> "You must be the change you wish to see in the world." -M. Gandhi<br>
><br>> _______________________________________________<br>> Baypiggies mailing list<br>> <a href="mailto:Baypiggies@python.org">Baypiggies@python.org</a><br>> To change your subscription options or unsubscribe:<br>
> <a href="http://mail.python.org/mailman/listinfo/baypiggies">http://mail.python.org/mailman/listinfo/baypiggies</a><br>><br><br></div></div>