Embedding Sphinx Docs in Hugo Websites

support
1

We would like to use Hugo to create a website for an ecosystem of several Python projects that are currently documented with Sphinx. Overall Hugo has worked out quite well! One operation that we are stuck on is the ability to “embed” the Sphinx documentation into the Hugo site so that we keep the Hugo-based header and footer so that users can navigate to non-documentation pages or the documentation of other modules within the ecosystem. Playing around with the Kube theme we have built the following example using iframes:

Untitled
Untitled.png1122×365 39.1 KB

While easy, there are some painful issues with this approach such as the inability to use back/forward, we cannot generate links to individual pages, and I am sure plenty of transgressions I am not aware of.

Another approach would be similar to the this example where the Sphinx header is replaced with one that has a common set of links and reused across several projects so that multiple websites appear to be unified to the user. While this works, it is not quite as flexible as having a full static site generator for non-document pages.

To summarize: we would like to use Hugo static site generation and insert of auto-generated docs from Sphinx that would replace the body of the Hugo site completely while still retaining the Hugo-based header and footers. Is there a canonical way to approach this problem?

2

I think your best option would be if you could:

  1. Generate some minimal front matter in the generated Sphinx files (I suspect a “—” start and end will do but you may consider creating a proper title)
  2. Generate to a section in /content
3

Sorry, I might be misunderstanding, but Sphinx generates a complete HTML website including its own CSS. It doesn’t look like a simple content or shortcode will be sufficient.

4

Your source files are in .rst text, for example: https://github.com/dgasmith/opt_einsum/blob/master/docs/source/index.rst

If you use that directory (with an external helper to use .rst), you can produce the entire site in Hugo. If you do, you’ll need to add front matter as bep mentioned.

Then Sphinx isn’t needed at all for the website.

5

The docutils with Hugo doesn’t support the sphinx-doc syntax. How to build sphinx-doc with Hugo?