On 25/01/2019 07.08, Peter Maydell wrote: > Hi; for the QEMU project we're looking to convert our existing > documentation to use Sphinx, and I have a question about how best to > structure things, which I haven't been able to find an answer for in the > documentation. > > For QEMU we (will) have effectively several different manuals, but we don't > want to ship them all to end users in "make install". To be concrete, we'll > have, say, a "User documentation" manual which we do want to ship, but also > a "Developer's guide" which deals with things that people working on QEMU > internals want to know. We don't want to install the dev guide on every > system, but it should be built in the source tree so that people using it > can refer to it. > > What's the best way to structure the sphinx docs so that we can do > something like: > * building in the source tree builds all the docs (user and dev) > * "make install" takes the subset of those docs that the user cares about > and copies them into the install directory, and that subset doesn't have > any cross references, links or index entries into documents that aren't > installed > ?
Do they need to cross-reference each other? If not, the easiest solution may be to just treat the two manuals as entirely separate. That is, separate directories in the repo, separate build steps, separate conf.py, etc... and then just don't write install rules for the dev guide. If the dev guide needs to link to the user guide, you can probably still accomplish this using intersphinx. Again, same deal, but the build rule for building the dev guide will depend on the rule for building the user manual so that the exported links are up to date. -- Matthew -- You received this message because you are subscribed to the Google Groups "sphinx-users" group. To unsubscribe from this group and stop receiving emails from it, send an email to sphinx-users+unsubscr...@googlegroups.com. To post to this group, send email to sphinx-users@googlegroups.com. Visit this group at https://groups.google.com/group/sphinx-users. For more options, visit https://groups.google.com/d/optout.
