I am currently working on a project that is attempting to ‘blend’ rst files from four separate git repos into arbitrary doc sets. Each repo represents a set of product documentation with its own tox/sphinx environment. We do this by, for example, symlinking a doc from repo A into B at runtime and using a combination of substitutions and include files to handle most customizations.
It can get complicated. Sometimes we need to cross link files and modify indexes, sometimes we want to add a document, but without certain files or sections. Sometimes we need to link just a subset of files or a single file from one repo into another. In some cases we need to link a doc from A (an open source product) to C (a proprietary version) and then ‘add’ some proprietary files to the linked content. Cross linking between repos is achieved using intersphinx, but since one repo is hosted by an ‘upstream’ open source partner, but contains content pulled into different downstream repos, we parse objects.inv from that project and modify local copies of the source files with the appropriate intersphinx tags. We run sphinx with the -W flag, so builds are picky about having exactly the .rst files required - and no more - in scope at build time. This works, but I am looking for a cleaner approach. Two alternatives may be: - Create a ‘meta’ repo from the four current repos and use it as a single source of content for builds. Since this would expose unused content to the builds, we would turn -W off and instead read build output into a loop, choosing which warnings to fail on. - Create a ‘meta’ repo from which we would pull the content required for a given build into a sphinx instance in a different location outside the repos, allowing us to continue to run strict builds (-W) and exposing only the artifacts required for a given build to sphinx. Has anyone dealt with a situation like this before? From my experience, Sphinx is not really intended to be used in a CMS type context, where a superset of content is mixed and matched into different subset configurations for different builds. Are we missing something about its behaviour that would allow a simpler approach? If not, has anyone come up with alternatives to the two options above or have experience with either? Thanks! -- 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 [email protected]. To view this discussion on the web visit https://groups.google.com/d/msgid/sphinx-users/ff33a7be-2350-453a-9837-77b3694f3ea3n%40googlegroups.com.
