Custom management commands and settings

[jordaneremieff]

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.

[carltongibson]

Hi @jordaneremieff — welcome, thanks! Glad you're keen: it seems like a good idea to me too. 😀

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?

Not sure. Generally the make json workflow is fine (for me) — we come in then with what we do with that, but open to ideas...

... 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.

Exposing more Sphinx stuff to the Django Template Language is definitely worth pursuing. There may be some prior art in contrib.admindocs that we could leverage.

[jordaneremieff]

So in regards to the replacing make json idea, I was thinking there could be a command like./manage.py sphinx init to generate the initial source and build directories. This command could use a SPHINX_ROOT_DIR Django setting (with a default), and the json_build_dir in the DocumentationView could be assumed as build under this root.

The other command would be ./manage.py sphinx build that wraps the sphinx-build command using arguments set in the Django settings file to replace the Makefile and make.bat files.

Then someone could just run these commands without any prior knowledge of Sphinx and bootstrap their documentation according to some template structure that generates it based on the settings - maybe with some boilerplate containing helpful "This is how you do X, Y, Z" content, etc.

I guess the main advantage that I see here is that it reduces the number of different tools that need to be configured and run separately. If you'd be open to something like this, then I might be able to sketch out and put forward a PoC to demonstrate further what I mean.

Exposing more Sphinx stuff to the Django Template Language is definitely worth pursuing. There may be some prior art in contrib.admindocs that we could leverage.

Ah, good point, that is definitely something worth exploring. My idea was a bit of a different angle (I think), but I'll try to dig into this a bit deeper.

[jordaneremieff]

Just to add a bit more context on the motivation here...

This suggestion is from the perspective of someone very familiar with Django but somewhat new to Sphinx (me). I've generally not used Sphinx because it has been fairly tedious to setup compared to something like MkDocs, but I've become more and more interested in Sphinx extensions (auto-documentation features in particular) and have decided it's worth it.

An alternative may be to create an example project that demonstrates the more standard workflow and how to connect these things to together rather than management commands.

[carltongibson]

Hey @jordaneremieff — thanks for the follow-up.

I'll just say that I lean towards sceptical about the management command... — I think sphinx-quickstart is pretty easy, and then make json or make html are too. Wrapper tools too often become a less-powerful, less-specific option, with a maintenance burden to boot.

I take your point though.

First pass I guess I'd learn towards a "Up & Running with Sphinx in 5 mins for Django Developers" for folks who aren't familiar.

It's not a No to any tools/commands, but I'd rather explore other options first. Let's see where the difficulties are once we've explored what already exists.

I hope that makes sense!

[jordaneremieff]

Thanks for the careful consideration @carltongibson, I agree with your points - let's wait and see.

I've only just started digging into this and Sphinx generally, so I'll see how I go and maybe can pinpoint some things that can be documented to make it easier to get rolling.

[jordaneremieff]

@carltongibson I created an example project here demonstrating a potential setup.

One thing that I think would be helpful for new users is documenting the path behavior in conf.py. The boilerplate from the Sphinx quickstart command produces # sys.path.insert(0, os.path.abspath('.')), but I needed to adjust this slightly and configure the Django settings module.

This is what I ended up with, but please let me know if there is a better pattern:

import os
import sys

sys.path.insert(0, os.path.abspath("../.."))
os.environ["DJANGO_SETTINGS_MODULE"] = "settings"

import django
django.setup()

Do you think something like this is worth including directly in this project under an example/ directory?

[carltongibson]

Hey @jordaneremieff — Yes, certainly!

I might have small comments on setting sys.path, but calling django.setup() is exactly right.