On Apr 26, 8:05 am, Brian Weidert <br...@mirusresearch.com> wrote: > Hey Greg, > > How's your documentation going? Any surprises in Sphinx or any advice you'd > pass on? I'm getting ready to document a project using Sphinx for the first > time so I was curious what advice you'd pass on. > Brian Weidert
Hi Brian, My overall impression? Sphinx Rocks! I'm still learning some of the finer points but, overall, I'm finding documenting a project to be fun! If you have the time, watch the Sphinx tutorial from PyCon 2010 by Brian Rhodes (IIRC, it's on blip tv, but Google is your friend). He talks about different types of documentation -- user, tutorial, and technical -- and how they differ. It's three hours long but there's a lot of good stuff demonstrated. I'm putting a class together at work because the heads of a couple other departments are interested in using Sphinx to document their (non Python) processes! I have yet to learn how to write extensions, but I may use a more basic approach (writing a program to create my "rst" files) to document our database and benefit schedules. Other than that, we're growing our documentation as the project is developed. By the time we hand it off if 6 months we should have a very impressive set of instructions. So, chalk me up as a fan. I've been programming for nearly 30 years now and have seen a lot of tools come and, thankfully, go. This one will be around for a while. Good luck! --greg > -----Original Message----- > From: sphinx-dev@googlegroups.com [mailto:sphinx-...@googlegroups.com] On > Behalf Of gslindstrom > Sent: Friday, April 16, 2010 10:57 AM > To: sphinx-dev > Subject: [sphinx-dev] Laying out documentation for a large project > > 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 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 > athttp://groups.google.com/group/sphinx-dev?hl=en. > > -- > 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 > athttp://groups.google.com/group/sphinx-dev?hl=en. > > -- 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.
