Hello all, We are evaluating to use Sphinx to generate our internal R&D documentation and specifications and we are thinking at the best way to layout the sources and the released pdf so that traceability and maintenance are not too difficult. In our context, developers consume specs and architects produce them.
1 We would like the developers to declare a published spec to which their product comply. There is also, concurrently a moving draft version that the architect edit. 2 The published specs are versioned so that it is possible to find the relevant specification even for a product developed two years ago 3 Architects have two repositories: the specification source repository with the rst and the conf.py, and they also have a repository with the released pdf documentation. 4 The repository of released pdf is not really mandatory (a shared filesystem is enough for the released docs) but is convenient for the traceability and distribution of the specification. The developers put an "svn external" link in their source repository toward the relevant specifications of the specification repository. When they checkout a source, they automagically get the relevant specs in the working copy. Also, it is explicit (and simple) to find the associated version of the specification in the source 5 the specification are versioned with two numbers : the major number bumps whenever there are addition of features, modification of an API: any incompatibility. It is the major version number that the developper decide to comply with, it is the major version number which appears on the released specification repository. The minor number make it possible for the architect to fix typos and enhance the documentation without breaking the developpers link. The minor number can be the subversion release number of the specification source repository. Here is the layout that we may adopt for our repositories: |-specs-src/ |-playlists/ |-playlists.rst |-figs/ |-circular_buffer/ |-circular_buffer.rst |-figs/ |-specs-released |-playlists/ |-01/ |-playlists-01.pdf |-02/ |-playlists-02.pdf |-circular-buffer/ |-01/ |-circular-buffer-01.pdf I am interested into all kind of advise, pointers, and feedback, Thank you, --~--~---------~--~----~------------~-------~--~----~ 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 -~----------~----~----~----~------~----~------~--~---
