Django's docs application as a reusable app

[Daniele Procida]

We've been looking at the application used by the Django Project to build and manage the Sphinx documentation:

<https://github.com/django/djangoproject.com/tree/master/docs>

We want similar functionality for some of our own websites, because doing it this way is a much more seamless way than having documentation hosted on Read the Docs, particularly from the point of view of the styling.

So, we want to explore the possibility of turning the application into a reusable application, that can easily be dropped into a Django-based website to build Sphinx documentation.

The application currently is quite tied into the deployment environment and configuration of the Django Project website, so some of the work will be be to abstract it from that.

A reusable version of the application will be useful for the many people who have Django sites and Sphinx documentation. It could be useful for the Django Project too, because abstracting its configuration and environment conditions will presumably make it easier to deploy the Django Project site in a different environment in the future.

If anyone's interested in being involved in this, let me know.

Regards,

Daniele

[Jannis Leidel]

Daniele,

> On 14 Aug 2015, at 13:56, Daniele Procida <dan...@vurt.org> wrote:
>
> We've been looking at the application used by the Django Project to build and manage the Sphinx documentation:

When you say we, who is that?

> <https://github.com/django/djangoproject.com/tree/master/docs>
>
> We want similar functionality for some of our own websites, because doing it this way is a much more seamless way than having documentation hosted on Read the Docs, particularly from the point of view of the styling.
>
> So, we want to explore the possibility of turning the application into a reusable application, that can easily be dropped into a Django-based website to build Sphinx documentation.
>
> The application currently is quite tied into the deployment environment and configuration of the Django Project website, so some of the work will be be to abstract it from that.

I’ve spent considerable amount of time in this code and would caution you to refactor this to be “reusable”. It’s purpose driven and was never intended to be used as a documentation build system. In fact it was a separate project once upon a time (https://github.com/django/djangoproject.com/commit/5f66182a5225a73be74f246789e4fcd9464f9ad0) and made it back into the central repo ever since. I also need to say that some design decisions made in the project are not best practices anymore.

> A reusable version of the application will be useful for the many people who have Django sites and Sphinx documentation. It could be useful for the Django Project too, because abstracting its configuration and environment conditions will presumably make it easier to deploy the Django Project site in a different environment in the future.
>
> If anyone's interested in being involved in this, let me know.

I’m not eager to collaborate at this point as it would essentially come close to a rewrite and we’re already short staffed on the Django websites team. If you’d turn it into a separate package the amount of customization and glue code to reintegrate it into the Django site code would be more work for us than we currently can handle. But at least the license is the same as Django’s so feel free to use it however you like. Just please understand that you’d probably be on your own.

In relation to that, have you looked at alternatives like

- https://pypi.python.org/pypi/django-sphinxdoc/
- https://pypi.python.org/pypi/django-docs
- https://github.com/rtfd/readthedocs.org

before?

Of course there is also the commercial offer from the ReadTheDocs folk at https://readthedocs.com/ that should be interesting for businesses that aim at using Sphinx for documentation. I hear that Eric and the others at RTD are good people and would welcome input from you.

Cheers,
Jannis

[Daniele Procida]

On Fri, Aug 14, 2015, Jannis Leidel <lei...@gmail.com> wrote:

>Daniele,
>
>> On 14 Aug 2015, at 13:56, Daniele Procida <dan...@vurt.org> wrote:
>>
>> We've been looking at the application used by the Django Project to
>build and manage the Sphinx documentation:
>
>When you say we, who is that?

We = Divio, http://divio.ch, and associated projects such as django CMS.

>I'm not eager to collaborate at this point as it would essentially come
>close to a rewrite and we're already short staffed on the Django
>websites team. If you'd turn it into a separate package the amount of
>customization and glue code to reintegrate it into the Django site code
>would be more work for us than we currently can handle. But at least the
>license is the same as Django's so feel free to use it however you like.
>Just please understand that you'd probably be on your own.
>
>In relation to that, have you looked at alternatives like
>
>- https://pypi.python.org/pypi/django-sphinxdoc/
>- https://pypi.python.org/pypi/django-docs
>- https://github.com/rtfd/readthedocs.org

Yes, we're looking at various ways of doing it, of which this is one.

>Of course there is also the commercial offer from the ReadTheDocs folk
>at https://readthedocs.com/ that should be interesting for businesses
>that aim at using Sphinx for documentation. I hear that Eric and the
>others at RTD are good people and would welcome input from you.

They certainly are - we use RTD a lot, and love it, and in fact we sponsor it too.

Thanks for the feedback.

Daniele