On Fri, Apr 16, 2010 at 8:57 AM, gslindstrom <[email protected]> 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 [email protected]. To unsubscribe from this group, send email to [email protected]. For more options, visit this group at http://groups.google.com/group/sphinx-dev?hl=en.
