[Baypiggies] Help: I'm being thick

[Jean Brouwers]

Glen,

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

<http://code.google.com/p/pympler/source/browse/trunk/doc/source/conf.py>
<http://code.google.com/p/pympler/source/browse/trunk/doc/source/index.rst>
The file or module names mentioned inside  index.rst have no extensions: all
names refer to .rst files.

Hope this helps,

/Jean Brouwers

PS) Just FYI, we made 3 changes to run Sphinx in a pympler-dev environment.
- The Makefile is not used and has been removed.

- Sphinx is run using the  sphinx.py script in the tools directory
<http://code.google.com/p/pympler/source/browse/trunk/tools/>.

- To build the docs, etc. we use the  run.py script in the top level
directory
<http://code.google.com/p/pympler/source/browse/#svn/trunk>, see the
 run_sphinx function in there.  Options --doctest, --html, --latex and
--linkcheck end up running Sphinx.

% ./run.py -h
Usage: run.py <options> [<args> ...]

 e.g. run.py --clean
      run.py --dist [--upload] [gztar] [zip]
      run.py --doctest
      run.py --html [--keep]
      run.py --latex [--paper=letter|a4]
      run.py --linkcheck
      run.py --pychecker [--OKd] [pympler | pympler/module] ...
      run.py --test [test | test/module | test/module/test_suite.py ...]

Options:
 -h, --help         show this help message and exit
 -a, --all          run all tests and create all documentation
 -c, --clean        remove bytecode files from source and test directories
 -d, --dist         create the distributions
 -D, --doctest      run the documentation tests
 -H, --html         create the HTML documentation
 -k, --keep         keep documentation in the doc directory
 -L, --latex        create the LaTeX (PDF) documentation
 --paper=PAPER      select LaTeX paper size (letter)
 -i, --linkcheck    check the documentation links
 -p, --pychecker    run static code analyzer PyChecker
 --OKd              include PyChecker warnings OKd in source
 -t, --test         run all or specific unit tests
 --upload           upload distributions to the Python Cheese Shop
 -V V, --verbose=V  set verbosity level (1)



On Wed, Feb 11, 2009 at 7:07 PM, Glen Jarvis <glen at glenjarvis.com> 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
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/baypiggies/attachments/20090211/d5e4735f/attachment-0001.htm>