Big docfix (#1464)

* use https wherever possible
* always point to python 3 doc
* point to new MSDN urls
* use RST references and avoid repetitions of URLs

1 files changed, 47 insertions, 33 deletions

diff --git a/docs/DEVGUIDE.rst b/docs/DEVGUIDE.rst
index f587ebcc..d9eb6d7a 100644
--- a/docs/DEVGUIDE.rst
+++ b/docs/DEVGUIDE.rst
@@ -21,11 +21,9 @@ If you plan on hacking on psutil this is what you're supposed to do first:
 
   make test
 
-- bear in mind that ``make``
-  (see `Makefile <https://github.com/giampaolo/psutil/blob/master/Makefile>`_)
-  is the designated tool to run tests, build, install etc. and that it is also
-  available on Windows
-  (see `make.bat <https://github.com/giampaolo/psutil/blob/master/make.bat>`_).
+- bear in mind that ``make``(see `Makefile`_) is the designated tool to run
+  tests, build, install etc. and that it is also available on Windows (see
+  `make.bat`_ ).
 - do not use ``sudo``; ``make install`` installs psutil as a limited user in
   "edit" mode; also ``make setup-dev-env`` installs deps as a limited user.
 - use `make help` to see the list of available commands.
@@ -33,10 +31,9 @@ If you plan on hacking on psutil this is what you're supposed to do first:
 Coding style
 ============
 
-- python code strictly follows `PEP 8 <https://www.python.org/dev/peps/pep-0008/>`_
-  styling guides and this is enforced by ``make install-git-hooks``.
-- C code strictly follows `PEP 7 <https://www.python.org/dev/peps/pep-0007/>`_
-  styling guides.
+- python code strictly follows `PEP-8`_ styling guides and this is enforced by
+  a commit GIT hook installed via ``make install-git-hooks``.
+- C code follows `PEP-7`_ styling guides.
 
 Makefile
 ========
@@ -100,30 +97,30 @@ Usually the files involved when adding a new functionality are:
 
 Typical process occurring when adding a new functionality (API):
 
-- define the new function in ``psutil/__init__.py``.
+- define the new function in `psutil/__init__.py`_.
 - write the platform specific implementation in ``psutil/_ps{platform}.py``
-  (e.g. ``psutil/_pslinux.py``).
+  (e.g. `psutil/_pslinux.py`_).
 - if the change requires C, write the C implementation in
-  ``psutil/_psutil_{platform}.c`` (e.g. ``psutil/_psutil_linux.c``).
-- write a generic test in ``psutil/tests/test_system.py`` or
-  ``psutil/tests/test_process.py``.
+  ``psutil/_psutil_{platform}.c`` (e.g. `psutil/_psutil_linux.c`_).
+- write a generic test in `psutil/tests/test_system.py`_ or
+  `psutil/tests/test_process.py`_.
 - if possible, write a platform specific test in
-  ``psutil/tests/test_{platform}.py`` (e.g. ``test_linux.py``).
+  ``psutil/tests/test_{platform}.py`` (e.g. `psutil/tests/test_linux.py`_).
   This usually means testing the return value of the new feature against
   a system CLI tool.
 - update doc in ``doc/index.py``.
 - update ``HISTORY.rst``.
-- update ``README.rst`` (if necessary).
 - make a pull request.
 
 Make a pull request
 ===================
 
-- fork psutil
-- create your feature branch (``git checkout -b my-new-feature``)
-- commit your changes (``git commit -am 'add some feature'``)
-- push to the branch (``git push origin my-new-feature``)
-- create a new pull request
+- fork psutil (go to https://github.com/giampaolo/psutil and click on "fork")
+- git clone your fork locally: ``git clone git@github.com:YOUR-USERNAME/psutil.git``)
+- create your feature branch:``git checkout -b new-feature``
+- commit your changes: ``git commit -am 'add some feature'``
+- push to the branch: ``git push origin new-feature``
+- create a new pull request by via github web interface
 
 Continuous integration
 ======================
@@ -136,13 +133,10 @@ Unit tests
 Tests are automatically run for every GIT push on **Linux**, **macOS** and
 **Windows** by using:
 
-- `Travis <https://travis-ci.org/giampaolo/psutil>`_ (Linux, macOS)
-- `Appveyor <https://ci.appveyor.com/project/giampaolo/psutil>`_ (Windows)
+- `Travis`_ (Linux, macOS)
+- `Appveyor`_ (Windows)
 
-Test files controlling these are
-`.travis.yml <https://github.com/giampaolo/psutil/blob/master/.travis.yml>`_
-and
-`appveyor.yml <https://github.com/giampaolo/psutil/blob/master/appveyor.yml>`_.
+Test files controlling these are `.travis.yml`_ and `appveyor.yml`_.
 Both services run psutil test suite against all supported python version
 (2.6 - 3.6).
 Two icons in the home page (README) always show the build status:
@@ -160,9 +154,8 @@ BSD, AIX and Solaris are currently tested manually.
 Test coverage
 -------------
 
-Test coverage is provided by `coveralls.io <https://coveralls.io/github/giampaolo/psutil>`_,
-it is controlled via `.travis.yml <https://github.com/giampaolo/psutil/blob/master/.travis.yml>`_
-and it is updated on every git push.
+Test coverage is provided by `coveralls.io`_ and it is controlled via
+`.travis.yml`_.
 An icon in the home page (README) always shows the last coverage percentage:
 
 .. image:: https://coveralls.io/repos/giampaolo/psutil/badge.svg?branch=master&service=github
@@ -172,9 +165,9 @@ An icon in the home page (README) always shows the last coverage percentage:
 Documentation
 =============
 
-- doc source code is written in a single file: `/docs/index.rst <https://raw.githubusercontent.com/giampaolo/psutil/master/docs/index.rst>`_.
-- it uses `RsT syntax <http://docutils.sourceforge.net/docs/user/rst/quickref.html>`_
-  and it's built with `sphinx <http://sphinx-doc.org/>`_.
+- doc source code is written in a single file: `/docs/index.rst`_.
+- it uses `RsT syntax`_
+  and it's built with `sphinx`_.
 - doc can be built with ``make setup-dev-env; cd docs; make html``.
 - public doc is hosted on http://psutil.readthedocs.io/
 
@@ -186,3 +179,24 @@ These are notes for myself (Giampaolo):
 - ``make release``
 - post announce (``make print-announce``) on psutil and python-announce mailing
   lists, twitter, g+, blog.
+
+
+.. _`.travis.yml`: https://github.com/giampaolo/psutil/blob/master/.travis.ym
+.. _`appveyor.yml`: https://github.com/giampaolo/psutil/blob/master/appveyor.ym
+.. _`Appveyor`: https://ci.appveyor.com/project/giampaolo/psuti
+.. _`coveralls.io`: https://coveralls.io/github/giampaolo/psuti
+.. _`doc/index.rst`: https://github.com/giampaolo/psutil/blob/master/doc/index.rst
+.. _`HISTORY.rst`: https://github.com/giampaolo/psutil/blob/master/HISTORY.rst
+.. _`make.bat`: https://github.com/giampaolo/psutil/blob/master/make.bat
+.. _`Makefile`: https://github.com/giampaolo/psutil/blob/master/Makefile
+.. _`PEP-7`: https://www.python.org/dev/peps/pep-0007/
+.. _`PEP-8`: https://www.python.org/dev/peps/pep-0008/
+.. _`psutil/__init__.py`: https://github.com/giampaolo/psutil/blob/master/psutil/__init__.py
+.. _`psutil/_pslinux.py`: https://github.com/giampaolo/psutil/blob/master/psutil/_pslinux.py
+.. _`psutil/_psutil_linux.c`: https://github.com/giampaolo/psutil/blob/master/psutil/_psutil_linux.c
+.. _`psutil/tests/test_linux.py`: https://github.com/giampaolo/psutil/blob/master/psutil/tests/test_linux.py
+.. _`psutil/tests/test_process.py`: https://github.com/giampaolo/psutil/blob/master/psutil/tests/test_process.py
+.. _`psutil/tests/test_system.py`: https://github.com/giampaolo/psutil/blob/master/psutil/tests/test_system.py
+.. _`RsT syntax`: http://docutils.sourceforge.net/docs/user/rst/quickref.htm
+.. _`sphinx`: http://sphinx-doc.org
+.. _`Travis`: https://travis-ci.org/giampaolo/psuti