Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP

Loading…

Docs build #273

Merged
4 commits merged into from

3 participants

@takluyver
Owner

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
Owner

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

@fperez
Owner

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
Owner

Looks like * is what we use.

@fperez
Owner

Thanks!

@takluyver
Owner

I've rebuilt and uploaded the docs, too.

@minrk
Owner

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
Owner

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
Owner

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
Owner

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
Owner

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

Thanks!

@minrk
Owner

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
Owner

pushed: 5285c57

@fperez
Owner

Great, thanks!

This issue was closed.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
This page is out of date. Refresh to see the latest.
Showing with 26 additions and 1 deletion.
  1. +4 −1 docs/gh-pages.py
  2. +22 −0 docs/source/development/doc_guide.txt
View
5 docs/gh-pages.py
@@ -110,7 +110,10 @@ def new_rstindex(fname, tag, desc=None):
try:
tag = sys.argv[1]
except IndexError:
- tag = sh2('git describe')
+ try:
+ tag = sh2('git describe')
+ except CalledProcessError:
+ tag = "dev" # Fallback
try:
desc = sys.argv[2]
View
22 docs/source/development/doc_guide.txt
@@ -133,6 +133,28 @@ docutils (the machinery to process reStructuredText):
In the past IPython used epydoc so currently many docstrings still use
epydoc conventions. We will update them as we go, but all new code should
be documented using the NumPy standard.
+
+Building and uploading
+======================
+The built docs are stored in a separate repository. Through some github magic,
+they're automatically exposed as a website. It works like this:
+
+* You will need to have sphinx and latex installed. In Ubuntu, install
+ ``texlive-latex-recommended texlive-latex-extra texlive-fonts-recommended``.
+ Install the latest version of sphinx from PyPI (``pip install sphinx``).
+* Ensure that the development version of IPython is the first in your system
+ path. You can either use a virtualenv, or modify your PYTHONPATH.
+* Switch into the docs directory, and run ``make gh-pages``. This will build
+ your updated docs as html and pdf, then automatically check out the latest
+ version of the docs repository, copy the built docs into it, and commit your
+ changes.
+* Open the built docs in a web browser, and check that they're as expected.
+* (If rebuilding the docs for the development version, it may have duplicated
+ the link to the development version in the homepage. Remove this from
+ index.rst, then run ``python build_index.py`` to update index.html. Commit the
+ change.)
+* Upload the docs with ``git push``. This only works if you have write access to
+ the docs repository.
.. [reStructuredText] reStructuredText. http://docutils.sourceforge.net/rst.html
.. [Sphinx] Sphinx. http://sphinx.pocoo.org/
Something went wrong with that request. Please try again.