Integrating Sphinx Documentation with django

Question

I have created sphinx documentation for a django project. It created a build folder an html folder and an index.html file. What im not to sure about is how to integrate the index.html file into my project. Is it possible to simply add it to url config and if how would it be formatted?

Answer 1

There are some good use cases for integrating sphinx doc into Django:

• Allow for dynamic content within documentation (i.e. user login, current time, etc).
• Integrate the documentation with your overall sitemap.
• Only one set of templates / CSS files to create and maintain.

If you have one or more of these needs, I would take a look at django-sphinxdoc, it handles all basic use cases out of the box but can be easily modified.

Answer 2

IMO, the 'best' way to do this is just at the HTTP server level and not in Django itself (at least that's how I've done it in the past). You don't need or want any pieces of Django layer to serve out your sphinx docs, you just need a 'vanilla' web server setup to do that.

Also, this could help Django urls straight to html template if you insist on using Django... but again, I'd vote to just setupt a /docs directory under your root and point it at the sphinx data via basic Apache/NGINX/etc config.