Hello. To start, I wanted to say thank you for creating this project! I've been interested in using Sphinx with Django like this for awhile, and I'm glad to see someone prominent in the Django community leading the way.

I've finally gotten around to playing around with it, and wanted to ask, would it make sense to include some custom management commands to replace the make files/build the docs and/or generate boilerplate templates in this project?

I was thinking these commands could be configured using Django settings (with sensible defaults) to inform things like paths, base templates, etc. to make it easier to get started. Beyond this, we could also look at other possibilities like wrapping sphinx-apidoc to make it easy to auto-generate API documentation for configured Django apps and the available models and direct the output based on the Django settings and/or a common pattern for including docs files.

Anyways, these are just a few things that came to mind that I thought might make it easier for people to use, especially those that are unfamiliar with configuring Sphinx. If you think these kinds of features might be a good fit here, then I'd be happy to contribute and discuss further.

Cheers.

Step down from a full theme.

Requires AppConfig and adding sphinx_view to INSTALLED_APPS for template

If json_build_dir doesn't exist you get a 404, which is OK, I guess, but it doesn't distinguish between, an expected, This page/URL doesn't exist, and, the misconfigured, The path you've given doesn't even map to a folder.

Better would be a system check to make sure it had a sane value. Is there a folder at json_build_dir? would likely be sufficient.

If this is outside the scope of django-sphinx-view, please feel free to close this.

I've been playing around with this package as a builder for fitness courses. I saw your talk, Carlton, and thought Sphinx + Django might work well for permission restricted access to courses.

For extensive online content, I find a global Table of Contents helpful in keeping the reader oriented and reminded of what they've learned already and what is still to come.

An example would be the Sphinx Book Theme, where there's a global ToC on the left and a document ToC on the right:

The local "toc" block supplied in the json output works wonders. Is there a way to render a similar toc but for the entire toctree structure? Perhaps with the "active" page tagged with a CSS class?

I could very well be missing something fundamental about the toctree directive. I've tried adding a new theme and combing through the json output, but no luck yet.

The initial rsync approach is fine, but...

• It depends on a node job to set up the SSH credentials.
• Much better to create an artefact and then notify that's it's available for collection.

GitHub Workflow Artifacts

Overview: Storing Workflow Data as Artifacts - GitHub Docs

Upload from the Workflow: Actions/Upload-artifact

Then fetch from via the API: REST API Endpoints for GitHub Actions Artifacts - GitHub Docs — About Artifacts... section.

• For public repos, no auth needed.
• For private repos a Fine Grained Personal Access Token will be needed, with the actions:read permission set.

Steps

• Have the docs build saved as an artifact. #30
• Script fetching from deployment host.
• Have that triggered, e.g. by a webhook.

Once settled:

• Restrict auto-deploy to tags.
• Document that folks should build the version they want otherwise.

Docs get rearranged. Links get broken.

Highlighting potential matches by path segment and/or search can help send folks on the right way.
You want that within a docs set though, not site-wide, so part of django-sphinx-view.

Hello,

I'm wondering if you would be able to make this an open-source project and provide a license?

Thanks

Follow-up to #12/#15 — adding global TOC.

By setting file-wide metadata, before any other markup:

:page_template: sphinx_view/no-globaltoc.html

… it's possibly to switch the template used to render each page, for example to not show the global TOC, on the index page, where it's already defined.

assert doc["meta"]["page_template"] == "sphinx_view/no-globaltoc.html"

1. Store the result of get_doc_json() on self. (As a @property? 🤔)
2. Re-use that in get_template_names() to see if doc["meta"]["page_template"] is set.

• Use that if so.
• Otherwise, self.template_name, as usual.

Today I ran into the same problem as @carltongibson did two years ago in pradyunsg/furo#89.
If I run make html, no problems. But make json throws:

Extension error (furo):
Handler <function _html_page_context at 0x108461ea0> for event 'html-page-context' threw an exception (exception: 'str' object is not callable)
make: *** [json] Error 2

This btw. only happens if conf.py contains extension = [..., "sphinx_view", ...], otherwise everything works fine. Therefore I assume it's more a problem of django-sphinx-view rather than furo itself.

Testet with various version combinations of furo and Sphinx. Currently the latest version of Sphinx (6.1.3) and furo (2023.3.27).

After commenting out html_theme = "furo" and adding "sphinx_view" to extension, make json also works fine.

• Licence file and trove classifier
• Other classifiers
• requires and python_requires.
• ...