Most open source projects store documentation in the source repo itself. This is easy to do, allows the doc builder to reference in-code documentation (like Python docstrings), makes contributions from others simpler, etc.

However, it doesn’t always play nice with “meta” information such as how to contribute, project roadmap, and so forth.

Projects that only publish docs for their latest release don’t have a problem here, but more advanced projects with multiple active release lines hit a snag: their “meta” content is now published in multiple places. If/when that content changes, inconsistencies will arise.

At the very least, this confuses hyperlinking (search results, bookmarks, links from third parties) and at worst it leads to conflicting information when old versions are no longer updated (or requires you to backport doc changes effectively forever.) This problem is exacerbated when you throw in blog/news style content.

Possible solutions

There are a few obvious ways to deal with this problem:

  • Ignore it;
  • Suck it up & do the work required to sync ‘meta’ content across all published doc versions;
  • Split ‘meta’ content out into its own repository, probably also publishing it as a distinct URI space from the ‘regular’ (now mostly API related) docs. (For example, see my thoughts on how to do this for Fabric’s docs.)

The first two are straightforward; the third exposes more possible breakdowns between the meta/static docs and the code-related/API docs:

  • Keep them wholly separate: different repositories & build/deploy pipelines. Maybe your API docs are Sphinx, hosted at Read The Docs while your meta content & project blog are a Pelican, Cactus or Octopress statically generated site (or use a non-static platform such as Wordpress or Django.)
    • Pluses: Total freedom regarding styling, feature set, content, etc; ability to reuse existing/preferred tools tailored for static/blog content.
    • Minuses: Poor branding, in that the two sites may look quite different.
  • Unified visually, distinct toolset: two deployments but with similar or identical visual styling (layout, logo, font, colors etc.) E.g. using similar stylesheets across RTD and an Octopress site.
    • Pluses: Consistent branding across your project’s doc content.
    • Minuses: Extra work, especially if you’re not great at HTML/CSS; possibly confusing for users who think the two projects are the same site for purposes of in-site search or navigation, when that is not the case.
  • Unified visually, same toolset: e.g. use RTD for API docs and a standalone Sphinx project for the meta site, both with the same Sphinx theme.
    • Pluses: One of the easier options; consistency is good.
    • Minuses: Same downside as previous option re: possibility for user confusion - especially if both are Sphinx-based and expose search fields!
  • Fully unified: use something like Git submodules to literally ‘refactor’ the static content out while leveraging the existing doc deploy toolchain.
    • Pluses: Super easy (well, barring the usual annoyances of submodules); path of least change from one’s existing site; no need to worry about styling, navigation or non-unified search.
    • Minuses: doesn’t solve the hyperlinking problem (multiple apparently-canonical copies of the meta docs are published online) and only partially solves the synch problem (you don’t have to merge, but you do still have to deploy every old edition of the docs anytime the submodule’s repo changes.)

Thoughts specific to my own projects

I currently use Read The Docs for my projects’ documentation (prose/meta and API) and Octopress for my personal site (which also functions as the blog for those projects.) Originally I thought to clone my personal site (whose style & featureset I am happy with) for per-project static sites.

However I realized its Spartan theme would make distinguishing the clones from each other & the original difficult. In addition, Octopress is Markdown driven; I prefer Markdown for standalone prose content, but it’s a poor fit for structured content - such as inter-linked multipage documentation. This lead me to the 3rd bullet point above: split the docs into two Sphinx repos, one versioned & hosted at RTD, the other statically hosted, both using the same theme.

The remaining issues with such a setup are:

  • Blog content - not something Sphinx is good at by default. Thankfully this looks solvable with Tinkerer which I need to, well, tinker with appears to no longer exist, as of the 2020s! Thanks, link checker.
  • User confusion regarding navigation. Hopefully this can be solved by having a prominent link to the “other side” in each project’s sidebar & landing page, though it will still hurt usability somewhat.
  • User confusion regarding search. I don’t see a way around this unless there’s a way for Sphinx’s JS driven search to query other Sphinx installations (I haven’t found one.) Will likely also “solve” this by adding a warning to both sites’ search results pages.