Fix up rst formatting

docs/source/coredev/index.rst

@@ -1,15 +1,15 b''
 .. _core_developer_guide:
 
 ==================================
-Developer's guide for core IPython
+Developer's guide to core IPython
 ==================================
 
-This guide documents the development of core *IPython itself*. Developers of
-third party tools and libraries that use IPython should see the 
-:doc:`development/index` at `Developer's guide for Third Party Tools and Libraries`.
+This guide documents the development of core IPython. Alternatively,
+developers of third party tools and libraries that use IPython should see the
+:doc:`../development/index`.
 
-Developers working on IPython itself should also consult the
-`developer information <https://github.com/ipython/ipython/wiki/Dev:-Index>`_ 
+Developers working on core IPython should also consult the
+`developer information <https://github.com/ipython/ipython/wiki/Dev:-Index>`_
 on the IPython GitHub wiki.
 
 .. toctree::

docs/source/coredev/old_release_doc.rst

@@ -1,7 +1,7 b''
 .. old_release_doc::
 
-Making an IPython release [TODO:: Can this be replaced by the Release Process document???]
-==========================================================================================
+Making an IPython release [TODO:: Can this content by removed ???]
+==================================================================
 
 Make sure the repository is clean of any file that could be problematic.
 You can remove all non-tracked files with:

docs/source/coredev/release_process.rst

@@ -10,11 +10,11 b' Conveniently, the `release` script in the `tools` directory of the `IPython`'
 repository automates most of the release process. This document serves as a
 handy reminder and checklist for the release manager.
 
-#. Set Environment variables
+1. Set Environment variables
 ----------------------------
 
 Set environment variables to document previous release tag, current
-release milestone, current release version, and git tag:
+release milestone, current release version, and git tag::
 
     PREV_RELEASE=rel-1.0.0
     MILESTONE=1.1
@@ -27,13 +27,13 b' questions instead of typing the appropriate command when the time comes. These'
 variables are not used by the scripts directly; therefore, there is no need to
 `export` the variables.
 
-#. Finish release notes
------------------------
+2. Create GitHub stats and finish release note
+----------------------------------------------
 
 .. note::
 
     Before generating the GitHub stats, verify that all closed issues and
-    pull requests `have appropriate milestones <https://github.com/ipython/ipython/wiki/Dev%3A-GitHub-workflow#milestones>`_.
+    pull requests have `appropriate milestones <https://github.com/ipython/ipython/wiki/Dev%3A-GitHub-workflow#milestones>`_.
     `This search <https://github.com/ipython/ipython/issues?q=is%3Aclosed+no%3Amilestone+is%3Aissue>`_
     should return no results before creating the GitHub stats.
 
@@ -58,49 +58,49 b' If a major release:'
       content from `stats.rst` may simply be added to the top of an existing
       `github-stats-X.rst` file.
 
-To find duplicates and update `.mailmap`, use:
+To find duplicates and update `.mailmap`, use::
 
     git log --format="%aN <%aE>" $PREV_RELEASE... | sort -u -f
 
 
-#. Run the `tools/build_release` script
+3. Run the `tools/build_release` script
 ---------------------------------------
 
-This does all the file checking and building that the real release script will
-do. This makes test installations, checks that the build procedure runs OK,
-and tests other steps in the release process.
+Running `tools/build_release` does all the file checking and building that
+the real release script will do. This makes test installations, checks that
+the build procedure runs OK, and tests other steps in the release process.
 
 We encourage creating a test build of the docs as well.
 
-#. Create and push the new tag
+4. Create and push the new tag
 ------------------------------
 
 Edit `IPython/core/release.py` to have the current version.
 
-Commit the changes to release.py and jsversion:
+Commit the changes to release.py and jsversion::
 
     git commit -am "release $VERSION"
     git push origin $BRANCH
 
-Create and push the tag:
+Create and push the tag::
 
     git tag -am "release $VERSION" "$TAG"
     git push origin --tags
 
-Update release.py back to `x.y-dev` or `x.y-maint`, and push:
+Update release.py back to `x.y-dev` or `x.y-maint`, and push::
 
     git commit -am "back to development"
     git push origin $BRANCH
 
-#. Get a fresh clone
+5. Get a fresh clone
 --------------------
 
-Get a fresh clone of the tag for building the release:
+Get a fresh clone of the tag for building the release::
 
     cd /tmp
     git clone --depth 1 https://github.com/ipython/ipython.git -b "$TAG"
 
-#. Run the release script
+6. Run the release script
 -------------------------
 
 Run the `release` script::
@@ -112,31 +112,38 b' them to archive.ipython.org and registers the release with PyPI.'
 
 This step requires having a current wheel, Python 3.4 and Python 2.7.
 
-#. Draft a short release announcement
+7. Draft a short release announcement
 -------------------------------------
 
-This should include i) highlights and ii) a link to the html version of
-the *What's new* section of the documentation.
+The announcement should include:
+
+- release highlights
+- a link to the html version of the *What's new* section of the documentation
+- a link to upgrade or installation tips (if necessary)
 
 Post the announcement to the mailing list, and link from Twitter.
 
-#. Update milestones on GitHub
+8. Update milestones on GitHub
 ------------------------------
 
+These steps will bring milestones up to date:
+
 - close the just released milestone
 - open a new milestone for the next release (x, y+1), if the milestone doesn't
   exist already
 
-#. Update the IPython website
+9. Update the IPython website
 -----------------------------
+
 The IPython website should document the new release:
 
 - add release announcement (news, announcements)
 - update current version and download links
 - update links on the documentation page (especially if a major release)
 
-#. Celebrate!
--------------
+10. Celebrate!
+--------------
 
-Celebrate the release and thank the contributors for their work.
+Celebrate the release and please thank the contributors for their work. Great
+job!
 

docs/source/development/index.rst

@@ -1,14 +1,14 b''
 .. _developer_guide:
 
 =====================================================
-Developer's guide for Third Party Tools and Libraries
+Developer's guide for third party tools and libraries
 =====================================================
 
-.. important:
+.. important::
 
     This guide contains information for developers of third party tools and
-    libraries that use IPython. Documentation for developers of co
-    *IPython itself* can be found in the :doc:`coredev/index`.
+    libraries that use IPython. Alternatively, documentation for core
+    **IPython** development can be found in the :doc:`../coredev/index`.
 
 .. toctree::
    :maxdepth: 1
@@ -19,53 +19,4 b" Developer's guide for Third Party Tools and Libraries"
    lexer
    pycompat
    config
-   inputhook_app
-
-Making an IPython release
-=========================
-
-Make sure the repository is clean of any file that could be problematic.
-You can remove all non-tracked files with:
-
-.. code::
-
-    git clean -xfdi
-
-This would ask you for confirmation before removing all untracked files. Make
-sure the ``dist/`` folder is clean and avoid stale build from
-previous attempts.
-
-1. Update version number in ``IPython/core/release.py``.
-
-Make sure the version number match pep440, in particular, `rc` and `beta` are
-not separated by `.` or the `sdist` and `bdist` will appear as different
-releases.
-
-2. Commit and tag the release with the current version number:
-
-.. code::
-
-    git commit -am "release $VERSION"
-    git tag $VERSION
-
-
-3. You are now ready to build the ``sdist`` and ``wheel``:
-
-.. code::
-
-    python setup.py sdist --formats=zip,gztar
-    python2 setup.py bdist_wheel
-    python3 setup.py bdist_wheel
-
-
-4. You can now test the ``wheel`` and the ``sdist`` locally before uploading to PyPI.
-Make sure to use `twine <https://github.com/pypa/twine>`_ to upload the archives over SSL.
-
-.. code::
-
-    $ twine upload dist/*
-
-5. If all went well, change the ``IPython/core/release.py`` back adding the ``.dev`` suffix.
-
-6. Push directly on master, not forgetting to push ``--tags``.
-
+   inputhook_app
  No newline at end of file