Documentation

[encode]

Documentation

[markotibold]

Hey,

there's a couple of things I'd like to discuss before I deep-dive into this.

• The structure of the main page of the docs should be simplified IMO. So some basic welcome stuff and links to relevant docs. I think the sphinx-homepage is a good reference implementation. So what needs to be done is write one index.html file like this one https://bitbucket.org/birkenfeld/sphinx/src/65e4c29a24e4/doc/_templates/index.html
  and keep the rest inside the .rst files. That way we can create one central contents page.
• Once we have the contents page, a logical structure will evolve from which we can build further.
• Furthermore I would personally pick a more readable theme. I've tried the sphinxdoc html theme and it looks pretty nice. It's more pleasant to read and more fun to write when things look nice.

Any disagreements?

[markotibold]

so, I've cooked up a couple of things in my fork and would like to have a little feedback on if this is the way to go.

See the commit log on the work that's been done.

TOX now also builds the docs, check the latest build here:

http://jenkins.tibold.nl/job/djangorestframework_markotibold/ws/TOXENV/docs/docs/html/index.html

And as you can see, we actually have a broken link in our docs:

http://jenkins.tibold.nl/job/djangorestframework_markotibold/TOXENV=docs/

gee

[tomchristie]

Can we also run that check outside of tox?

Also couldn't quite figure out what/where the broken link was - is mentioned in the test results somewhere?

[markotibold]

Op 15 dec. 2011 om 10:01 heeft Tom [email protected] het volgende geschreven:

Can we also run that check outside of tox?
Yup. I will add a seperate scriptfor that or so.

Also couldn't quite figure out what/where the broken link was - is mentioned in the test results somewhere?
I see what you mean. The xml output is not very clear on that. If you search for 404 in the output. You'll find it.

---

Reply to this email directly or view it on GitHub:
#15 (comment)

[markotibold]

The output is much clearer now:

http://jenkins.tibold.nl/job/djangorestframework_markotibold/TOXENV=docs/lastCompletedBuild/testReport/(root)/check_sphinx/test_linkcheck/

[tomchristie]

Ok. Correct link should be:

https://docs.djangoproject.com/en/dev/howto/deployment/modpython/#serving-the-admin-files

[markotibold]

Link fixed in tip.

[tomchristie]

Also, I'm not quite sure why this has only occurred to me just now, but...

I'm obviously super-keen that the docs should live at http://django-rest-framework.org, which is pretty much the reason that I'm hosting them myself at the moment, but that's not really necessary. readthedocs supports having a custom domain point at your documentation, as well as supporting post commit hooks, and versioning.

I've added a post commit hook, and so long as we tag versions properly it'll pick those up too.

I think it's going to be the least-effort choice, so I'm pretty keen to go with that, so we can concentrate on other stuff.

Obv. having the docs build in CI is still super useful, as it'll show us broken links, and lets us test the docs building before doing checkins. But in terms of where we should host the docs I think RTD is going to make sense...

See: http://django-rest-framework.rtfd.org

If this make sense to you I'll consider switching the domain name over later this week...

[tomchristie]

Also worth noting that it does seem to support custom themes too... http://celery.readthedocs.org/

[markotibold]

linkcheck tends to fail, if the pages aren't loaded fast enough, so need to see if we can set a timeout of some sort.

I made a seperate project for the docs, cause there's no coverage report bening generated and the main job fails when it finds no coverage reports. Yet there does seem to be some coverage checking we can do with sphinx: http://sphinx.pocoo.org/ext/coverage.html#module-sphinx.ext.coverage

[markotibold]

Btw hosting at readthedocs makes a lot of sense to me!

[tomchristie]

Having the docs tested * separately* on the CI sounds like a very good plan. We don't want our build flagging as failed just because some site we link to in our docs has temporarily gone down.

[markotibold]

I managed to push upstream from my fork. Which worked pretty well.

New setup of jenkins also applied for main branch now.

[markotibold]

Hey Tom,

Looks like you have setup your readthedocs account pretty nicely. I love
the multiple version support as well.

I guess the 'latest' is just pulled from HEAD right? Is it updated
automagically?

I think it's still a good idea to have the docs built on the CI, to see if
anything breaks. I don't know what behavvior is defined for readthedocs
when it builds the latest docs from HEAD. Does it stop or will it publish
docs even if errors or warnings occur during the build? I've checked their
faq and docs, but it;s not mentioned.

Cheers,

Marko

On 15 December 2011 17:18, Tom Christie <
[email protected]

wrote:

Having the docs tested * separately* on the CI sounds like a very good
plan. We don't want our build flagging as failed just because some site we
link to in our docs has temporarily gone down.

---

Reply to this email directly or view it on GitHub:

#15 (comment)

[tomchristie]

Yeah it's cool. Builds automatically on checkin, and if we tag the versions properly in github it's manage those for us too. (See: http://help.github.com/git-cheat-sheets/ for tagging.)

I think it's still a good idea to have the docs built on the CI, to see if anything breaks.

Sounds ok with me, tho not too much fussed either way. rtd won't do anything clever if the docs fail.

I haven't pushed the domain over to rtd yet, I need to chat with the maintainer, see if it's possible to get the google analytics key entered for rest framework.

[tomchristie]

I'm going to close this ticket as being under-defined. Obv, theres still work to do on the docs, but I'm going to try to maintain the ticket backlog more strictly now.