Docs build #273

Merged
4 commits merged into from Feb 14, 2011

Conversation

Projects
None yet
3 participants
@takluyver
Member

takluyver commented Feb 14, 2011

Based on my experience of building the docs, here's a brief description in the docs of how to do it (I've checked that it builds OK as html). I've also added a fallback to the gh-pages.py script, so it doesn't crash in the absence of a named tag.

I think the main thing to check is: is the description of the process I've given in the docs sufficient? Is there anyone who's not previously built the docs who's willing to try following these instructions, to see if it's clear enough?

@takluyver

This comment has been minimized.

Show comment Hide comment
@takluyver

takluyver Feb 14, 2011

Member

Oh, and I've just noticed that other parts of the docs use * rather than - for bullets. Should I change this for consistency?

Member

takluyver commented Feb 14, 2011

Oh, and I've just noticed that other parts of the docs use * rather than - for bullets. Should I change this for consistency?

@fperez

This comment has been minimized.

Show comment Hide comment
@fperez

fperez Feb 14, 2011

Member

The changes look good, go ahead with the merge. And about */-: just have a quick look throughout, if indeed we had been consistently using *, then might as well not break that. But if we were using both (quite possible, since reST is ok with both), then don't worry.

Member

fperez commented Feb 14, 2011

The changes look good, go ahead with the merge. And about */-: just have a quick look throughout, if indeed we had been consistently using *, then might as well not break that. But if we were using both (quite possible, since reST is ok with both), then don't worry.

@takluyver

This comment has been minimized.

Show comment Hide comment
@takluyver

takluyver Feb 14, 2011

Member

Looks like * is what we use.

Member

takluyver commented Feb 14, 2011

Looks like * is what we use.

@fperez

This comment has been minimized.

Show comment Hide comment
@fperez

fperez Feb 14, 2011

Member

Thanks!

Member

fperez commented Feb 14, 2011

Thanks!

@takluyver

This comment has been minimized.

Show comment Hide comment
@takluyver

takluyver Feb 14, 2011

Member

I've rebuilt and uploaded the docs, too.

Member

takluyver commented Feb 14, 2011

I've rebuilt and uploaded the docs, too.

@minrk

This comment has been minimized.

Show comment Hide comment
@minrk

minrk Feb 15, 2011

Member

note that it's make gh-pages-current that actually does the correct action for updating the current dev docs. gh-pages works like this:

python gh-pages.py

We could eliminate the extra make gh-pages-current command, and do what happens there in make gh-pages.

Member

minrk commented Feb 15, 2011

note that it's make gh-pages-current that actually does the correct action for updating the current dev docs. gh-pages works like this:

python gh-pages.py

We could eliminate the extra make gh-pages-current command, and do what happens there in make gh-pages.

@fperez

This comment has been minimized.

Show comment Hide comment
@fperez

fperez Feb 15, 2011

Member

Actually I think we could just do away with the automatic adding of a line to the index that I had in datarray. While convenient there, for quick and short releases, in IPython I think we're better off just rebuilding the -dev docs by default, and calling the script manually for a release build. In the case of a release, it's no big burden to add manually the extra link.

This would simplify both the code and the usage, since the index.rst page would be fully manually edited, and the script would be limited to one of two actions:

  1. Buidling dev/, default action.
  2. Building an explicit tag (such as for a release).

Anyone wanting to have a stab at it, go for it :)

Member

fperez commented Feb 15, 2011

Actually I think we could just do away with the automatic adding of a line to the index that I had in datarray. While convenient there, for quick and short releases, in IPython I think we're better off just rebuilding the -dev docs by default, and calling the script manually for a release build. In the case of a release, it's no big burden to add manually the extra link.

This would simplify both the code and the usage, since the index.rst page would be fully manually edited, and the script would be limited to one of two actions:

  1. Buidling dev/, default action.
  2. Building an explicit tag (such as for a release).

Anyone wanting to have a stab at it, go for it :)

@minrk

This comment has been minimized.

Show comment Hide comment
@minrk

minrk Feb 15, 2011

Member

Sure thing, I'll do that now. Summary:

  • remove the index edits from gh-pages.py
  • remove gh-pages-current from makefile
  • ensure make gh-pages builds dev
Member

minrk commented Feb 15, 2011

Sure thing, I'll do that now. Summary:

  • remove the index edits from gh-pages.py
  • remove gh-pages-current from makefile
  • ensure make gh-pages builds dev
@takluyver

This comment has been minimized.

Show comment Hide comment
@takluyver

takluyver Feb 15, 2011

Member

If you're going to change that, don't forget to remove the note about it that I added in the docs.

Also, I've made gh-pages.py assume a default tag of "dev" - I don't know how that fits in with what you want to do.

Member

takluyver commented Feb 15, 2011

If you're going to change that, don't forget to remove the note about it that I added in the docs.

Also, I've made gh-pages.py assume a default tag of "dev" - I don't know how that fits in with what you want to do.

@fperez

This comment has been minimized.

Show comment Hide comment
@fperez

fperez Feb 15, 2011

Member

Min, sounds good, with Thomas' comments in mind.

Thanks!

Member

fperez commented Feb 15, 2011

Min, sounds good, with Thomas' comments in mind.

Thanks!

@minrk

This comment has been minimized.

Show comment Hide comment
@minrk

minrk Feb 15, 2011

Member

I had been thinking of manually specifying the tag in the Makefile, but I will use your dev default, so it can still be used to build other releases from the Makefile without directly calling gh-pages.py.

The note was already in error, because it wasn't possible to create a duplicate release line if you used the correct makefile command (currently 'gh-pages-current', but will be 'gh-pages' after the fix) for the dev docs. I will update the doc page to match.

Thanks for the note.

Member

minrk commented Feb 15, 2011

I had been thinking of manually specifying the tag in the Makefile, but I will use your dev default, so it can still be used to build other releases from the Makefile without directly calling gh-pages.py.

The note was already in error, because it wasn't possible to create a duplicate release line if you used the correct makefile command (currently 'gh-pages-current', but will be 'gh-pages' after the fix) for the dev docs. I will update the doc page to match.

Thanks for the note.

@minrk

This comment has been minimized.

Show comment Hide comment
@minrk

minrk Feb 15, 2011

Member

pushed: 5285c57

Member

minrk commented Feb 15, 2011

pushed: 5285c57

@fperez

This comment has been minimized.

Show comment Hide comment
@fperez

fperez Feb 15, 2011

Member

Great, thanks!

Member

fperez commented Feb 15, 2011

Great, thanks!

This issue was closed.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment