Integrating Django Views into served docs

[jrief]

Hi Carlton,
first of all, many thanks for this library, it really helps me to serve documentation through Django.

Integrating Django Views

My main reason for using this library was that I wanted to integrate Django views inside the transformed documentation. I succeeded in doing so, by introducing a new Sphinx directive, which is similar to the

.. code-block:: python

but named

.. django-view:: <custom_view_function>

In addition to rendering the code block, it also integrates the rendered Django view into the documentation. I added this, because I want to explain the use of the widgets provided by the django-formset library. I now can use a working demo and integrate it into a ReStructured text-document. This might be a feature, which could be useful to other authors.

However, while working with django-sphinx-view, I came across some issues unable to solve myself, which forced me to change fundamental parts of your code.

Searching

I'm using the Furo theme, but using other themes might have the same issue. The template required to render the search results must be slightly different than the template used to render content pages. Here I overwrote the get_templates()-method. I also had to patch the Javascript file searchtools.js, because that one provided by Sphinx has some issues, when fetching content from the Django server.

To get this working, I also had to overwrite the method add_sidebars() in the SphinxViewBuilder, otherwise the search result page does not render a doc-tree.

Index on Site-Root

Unfortunately I was unable to run a site which serves the index-page as a site-root. I was able to solve this, by adding a file urls.py to the project, which then adds the urlpatterns for the index-, search-, content- and the Django demo
views, mentioned before.

All these changes might be well beyond the scope you intended for this library.

However, I believe they might be useful for other authors of 3rd party libraries, especially if they want to add working samples of their Django views into the project. I often see Javascript libraries which to exactly that, for example Shoelace Carousel, Flowbite Carousel, Bootstrap Carousel, etc. and think it's a pity that we do (did) not have this possibility in Django and Sphinx.

I'd therefore like to ask how to proceed with these changes. A simple pull request will certainly break backwards compatibility, but I believe that the benefits outweigh this by far.

This is my fork: https://github.com/jrief/django-sphinx-view

Hope to see you in Edinburgh,
Jacob

[carltongibson]

Hey Jacob. Thanks for posting.

This all sounds very interesting!

I've been experimenting with using HTMX's hx-trigger=load to pull in a live view to the rendered docs, so comparing notes here would be good.

I am aware of the search page issue — we could likely address that in a PR no?

Unfortunately I was unable to run a site which serves the index-page as a site-root. I was able to solve this, by adding a file urls.py to the project, which then adds the urlpatterns for the index-, search-, content- and the Django demo
views, mentioned before.

This sounds interesting too. Let me look at your fork 👀

(Life is a bit 🤯 ATM, just FYI)