On Fri, Apr 16, 2010 at 8:57 AM, gslindstrom gslindst...@gmail.com wrote:
Hello,
We are starting a large project where I work and I would like to start
documenting it *now* rather than later. Sphinx looks like the ideal
tool for the job (I've been playing with it for a month or two but,
now, it's time to get serious).
Are there thoughts on whether I should put all my documentation in one
directory (docs) under the main project directory or would I have the
same docs directory but with each sub-part of the project (build,
www, lib, test) having it's own docs directory holding information
on that particular area and having the master docs tie them all
together? My thinking is it might be nice to have the documentation
closer to the actual code.
If I were to have separate doc directories (one under each sub-part),
how do I link the main toctree (in myproject/docs/source/index.rst) to
the sub-parts (say, my_project/www/docs/index.rst)? I've tried Web
Documentation ../../www/docs/index, but it does not find it. I've
heard that I can't go up like that to get to other directories;
don't recall where I read it, but I thought I would ask here.
And, as long as I am asking, if I have another routine that I have
already documented with Sphinx, how do I include it with this project
(it's a routine extending the logger routine in the Standard Library
that my_project will use. I don't want it in the user
documentation, but would like it in the technical referrence portion
of my_project documentation. Perhaps it is enough to have a
dependencies page listing all of the third-party routines.
I hope I have made sense, because I'm a bit overwhelmed. I've never
been a fan of documentation but am committed to giving this a go.
Thanks for your replies,
Greg Lindstrom
Novasys Health (Little Rock, AR)
You might want to look at the doc directory of a recent Python (2.6.x
or 3.1.x) *source* distribution from http://python.org/download/. It's
probably the biggest real world example of using Sphinx.
--
You received this message because you are subscribed to the Google Groups
sphinx-dev group.
To post to this group, send email to sphinx-...@googlegroups.com.
To unsubscribe from this group, send email to
sphinx-dev+unsubscr...@googlegroups.com.
For more options, visit this group at
http://groups.google.com/group/sphinx-dev?hl=en.
