Updated Documentation (Fixes #77)

circuits · Jun 2, 2015 · ca70f7d · ca70f7d
1 parent d11adca
commit ca70f7d
Show file tree

Hide file tree

Showing 12 changed files with 70 additions and 77 deletions.
diff --git a/README.rst b/README.rst
@@ -5,11 +5,13 @@
 .. _MIT License: http://www.opensource.org/licenses/mit-license.php
 .. _Create an Issue: https://github.com/circuits/circuits/issues/new
 .. _Mailing List: http://groups.google.com/group/circuits-users
-.. _Project Website: http://circuitsframework.com/
-.. _PyPi Page: http://pypi.python.org/pypi/circuits
-.. _Read the Docs: http://circuits.readthedocs.org/en/latest/
-.. _View the ChangeLog: http://circuits.readthedocs.org/en/latest/changes.html
-.. _Downloads Page: https://github.com/circuits/circuits/releases
+.. _Website: http://circuitsframework.com/
+.. _PyPi: http://pypi.python.org/pypi/circuits
+.. _Documentation: http://circuits.readthedocs.org/en/latest/
+.. _Downloads: https://github.com/circuits/circuits/releases
+.. _Ask a Question: http://stackoverflow.com/questions/ask
+.. _Stackoverflow: http://stackoverflow.com/
+.. _Google+ Group: https://plus.google.com/communities/107775112577294599973
 
 .. image:: https://travis-ci.org/circuits/circuits.svg
    :target: https://travis-ci.org/circuits/circuits
@@ -39,10 +41,13 @@ circuits also includes a lightweight, high performance and scalable
 HTTP/WSGI compliant web server as well as various I/O and Networking
 components.
 
-- Visit the `Project Website`_
-- `Read the Docs`_
-- Download it from the `Downloads Page`_
-- `View the ChangeLog`_
+- `Website`_
+- `Downloads`_
+- `Documentation`_
+
+Got questions? 
+
+- `Ask a Question`_ (Tag it: ``circuits-framework``)
 
 
 Examples
@@ -90,7 +95,7 @@ If you do not have pip, you may use easy_install::
     $ easy_install circuits
 
 Alternatively, you may download the source package from the
-`PyPi Page`_ or the `Downloads Page`_ extract it and install using::
+`PyPi`_ or the `Downloads`_ extract it and install using::
 
     $ python setup.py install
 
@@ -123,6 +128,9 @@ work with you to either incorporate the idea or find a better solution.
 Community
 ---------
 
-There is also a small community of circuits enthusiasts that you may
-find on the `#circuits IRC Channel`_ on the `FreeNode IRC Network`_
-and the `Mailing List`_.
+There are also several places you can reach out to the circuits community:
+
+- `Mailing List`_
+- `Google+ Group`_
+- `#circuits IRC Channel`_ on the `FreeNode IRC Network`_
+- `Ask a Question`_ on `Stackoverflow`_ (Tag it: ``circuits-framework``)
diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -41,8 +41,6 @@
 # coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
 extensions = []
 
-bitbucket_project_url = 'https://bitbucket.org/circuits/circuits'
-
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
 
@@ -109,8 +107,8 @@
 
 # 'releases' (changelog) settings
 releases_debug = True
-releases_issue_uri = "https://bitbucket.org/circuits/circuits/issue/%s"
-releases_release_uri = "https://bitbucket.org/circuits/circuits/src/tip/?at=%s"
+releases_issue_uri = "https://github.com/circuits/circuits/issues/%s"
+releases_release_uri = "https://github.com/circuits/circuits/tree/%s"
 releases_document_name = "changes"
 
 # The language for content autogenerated by Sphinx. Refer to documentation

diff --git a/docs/source/dev/contributing.rst b/docs/source/dev/contributing.rst
@@ -1,3 +1,7 @@
+.. _Fork circuits: https://github.com/circuits/circuits/issues/new#fork-destination-box
+.. _Create an Issue: https://github.com/circuits/circuits/issues/new
+.. _Pull Request: https://github.com/circuits/circuits/compare/
+
 Contributing to circuits
 ========================
 
@@ -25,17 +29,16 @@ and concise form with repeatable steps. One of the best ways you can report
 a bug to us is by writing a unit test (//similar to the ones in our tests//)
 so that we can verify the bug, fix it and commit the fix along with the test.
 
-To submit a bug report, please use:
- http://bitbucket.org/circuits/circuits/issues
+To submit a bug report, please `Create an Issue`_
 
 
 Writing new tests
 -----------------
 
 
 We're not perfect, and we're still writing more tests to ensure quality code.
-If you'd like to help, please `Fork circuits <https://bitbucket.org/circuits/circuits/fork>`_, write more tests that cover more of our code base and
-submit a `Pull Request <https://bitbucket.org/circuits/circuits/pull-request/new>`_. Many Thanks!
+If you'd like to help, please `Fork circuits`_, write more tests that cover more
+of our code base and submit a `Pull Request`_. Many Thanks!
 
 
 Adding New Features
@@ -50,4 +53,4 @@ as valid use-cases. To start the discussions off, please either:
 
   or
 
-- `Submit a **New** Issue <http://bitbucket.org/circuits/circuits/issues>`_
+- `Create an Issue`_
diff --git a/docs/source/dev/introduction.rst b/docs/source/dev/introduction.rst
@@ -1,5 +1,5 @@
 .. _Developer Mailing List: http://groups.google.com/group/circuits-dev
-.. _Issue Tracker: https://bitbucket.org/circuits/circuits/issues
+.. _Issue Tracker: https://github.com/circuits/circuits/issues
 .. _FreeNode IRC Network: http://freenode.net
 .. _IRC Channel: http://webchat.freenode.net/?randomnick=1&channels=circuits&uio=d4
 
@@ -28,7 +28,7 @@ Standards
 
 We use the following coding standard:
 
-- `pep8 <http://www.python.org/dev/peps/pep-0008/>`_
+- `PEP-008 <http://www.python.org/dev/peps/pep-0008/>`_
 
 We also lint our codebase with the following tools:
 
@@ -50,15 +50,16 @@ Tools
 We use the following tools to develop circuits and share code:
 
 - **Code Sharing:**
-  `Mercurial <http://mercurial.selenic.com/>`_
+  `Git <https://git-scm.com/>`_
 - **Code Hosting and Bug Reporting:**
-  `BitBucket <https://bitbucket.org/circuits/circuits>`_
-  `GitHub <https://github.com/circuits/circuits>`_ (*Mirror Only*)
+  `GitHub <https://github.com/circuits/circuits>`_
 - **Issue Tracker:**
-  `Issue Tracker <https://bitbucket.org/circuits/circuits/issues>`_
+  `Issue Tracker <https://github.com/circuits/circuits/issues>`_
 - **Documentation Hosting:**
   `Read the Docs <http://circuits.readthedocs.org>`_
 - **Package Hosting:**
   `Python Package Index (PyPi) <http://pypi.python.org/pypi/circuits>`_
 - **Continuous Integration:**
-  `Drone <https://drone.io/bitbucket.org/circuits/circuits>`_
+  `Travis CI <https://travis-ci.org/circuits/circuits>`_
+- **Code Quality:**
+  `Landscape <https://landscape.io/github/circuits/circuits/>`_
diff --git a/docs/source/dev/processes.rst b/docs/source/dev/processes.rst
@@ -1,4 +1,4 @@
-.. _Issue Tracker: https://bitbucket.org/circuits/circuits/issues
+.. _Issue Tracker: https://github.com/circuits/circuits/issues
 
 
 Development Processes
@@ -14,58 +14,59 @@ Software Development Life Cycle (SDLC)
 --------------------------------------
 
 
-We employ the use of the `SCRUM Agile Process <http://en.wikipedia.org/wiki/Scrum_(development)>`_ and use our `Issue Tracker`_ to track
-features, bugs, chores and releases. If you wish to contribute
-to circuits, please familiarize yourself with SCRUM and `BitBucket <https://bitbucket.org/>`'s Issue Tracker.
+We employ the use of the `SCRUM Agile Process <http://en.wikipedia.org/wiki/Scrum_(development)>`_
+and use our `Issue Tracker`_ to track features, bugs, chores and releases.
+If you wish to contribute to circuits, please familiarize yourself with SCRUM
+and `GitHub <https://github.com>`_'s Issue Tracker.
 
 
 Bug Reports
 -----------
 
 
 - New Bug Reports are submitted via:
-  http://bitbucket.org/circuits/circuits/issues
+  https://github.com/circuits/circuits/issues
 - Confirmation and Discussion of all New Bug Reports.
 - Once confirmed, a new Bug is raised in our `Issue Tracker`_
 - An appropriate milestone will be set (*depending on current milestone's schedule and resources*)
 - A unit test developed that demonstrates the bug's failure.
 - A fix developed that passes the unit test and breaks no others.
-- A `New Pull Request <https://bitbucket.org/circuits/circuits/pull-request/new>`_ created with the fix.
+- A `New Pull Request <https://github.com/circuits/circuits/compare/>`_ created with the fix.
 
   This must contains:
   - A new or modified unit test.
   - A patch that fixes the bug ensuring all unit tests pass.
-  - The `Change Log <https://bitbucket.org/circuits/circuits/src/tip/CHANGES.rst>`_ updated.
+  - The `Change Log <https://github.com/circuits/circuits/tree/master/CHANGES.rst>`_ updated.
   - Appropriate documentation updated.
-- The `Pull Request <https://bitbucket.org/circuits/circuits/pull-request>`_ is reviewed and approved by at least two other developers.
+- The `Pull Request <https://github.com/circuits/circuits/pulls>`_ is reviewed and approved by at least two other developers.
 
 
 Feature Requests
 ----------------
 
 
 - New Feature Requests are submitted via:
-  http://bitbucket.org/circuits/circuits/issues
+  https://github.com/circuits/circuits/issues
 - Confirmation and Discussion of all New Feature Requests.
 - Once confirmed, a new Feature is raised in our `Issue Tracker`_
 - An appropriate milestone will be set (*depending on current milestone's schedule and resources*)
 - A unit test developed that demonstrates the new feature.
 - The new feature developed that passes the unit test and breaks no others.
-- A `New Pull Request <https://bitbucket.org/circuits/circuits/pull-request/new>`_ created with the fix.
+- A `New Pull Request <https://github.com/circuits/circuits/compare/>`_ created with the fix.
 
   This must contains:
   - A new or modified unit test.
   - A patch that implements the new feature ensuring all unit tests pass.
-  - The `Change Log <https://bitbucket.org/circuits/circuits/src/tip/CHANGES.rst>`_ updated.
+  - The `Change Log <https://github.com/circuits/circuits/tree/master/CHANGES.rst>`_ updated.
   - Appropriate documentation updated.
-- The `Pull Request <https://bitbucket.org/circuits/circuits/pull-request>`_ is reviewed and approved by at least two other developers.
+- The `Pull Request <https://github.com/circuits/circuits/pulls>`_ is reviewed and approved by at least two other developers.
 
 
 Writing new Code
 ----------------
 
 
-- Submit a `New Issue <https://bitbucket.org/circuits/circuits/issues/new>`_
+- Submit a `New Issue <https://github.com/circuits/circuits/issues/new>`_
 - Write your code.
 - Use `flake8 <http://pypi.python.org/pypi/flake8>`_ to ensure code quality.
 - Run the tests::
@@ -74,8 +75,8 @@ Writing new Code
 
 - Ensure any new or modified code does not break existing unit tests.
 - Update any relevant doc strings or documentation.
-- Update the `Change Log <https://bitbucket.org/circuits/circuits/src/tip/CHANGES.rst>`_ updated.
-- Submit a `New Pull Request <https://bitbucket.org/circuits/circuits/pull-request/new>`_.
+- Update the `Change Log <https://github.com/circuits/circuits/tree/master/CHANGES.rst>`_ updated.
+- Submit a `New Pull Request <https://github.com/circuits/circuits/compare/>`_.
 
 
 Running the Tests
@@ -88,7 +89,7 @@ To run the tests you will need the following installed:
 - `pytest-cov <http://pypi.python.org/pypi/pytest-cov>`_
 - `pytest <http://pytest.org/latest/>`_
 
-All of these can be installed via ``easy_install`` or ``pip``.
+All of these can be installed via ``pip``.
 
 Please also ensure that you you have all supported versions of Python
 that circuits supports installed in your local environment.

diff --git a/docs/source/examples/index.rst b/docs/source/examples/index.rst
@@ -36,4 +36,4 @@ Download Source Code: :download:`helloweb.py: <examples/helloweb.py>`
 
 
 
-More `examples <https://bitbucket.org/circuits/circuits/src/tip/examples/>`_...
+More `examples <https://github.com/circuits/circuits/tree/master/examples/>`_...
diff --git a/docs/source/man/components.rst b/docs/source/man/components.rst
@@ -153,5 +153,5 @@ Example:
     set([<Foo/* 28599:MainThread (queued=0) [S]>])
     >>> 
 
-The `telnet Example <https://bitbucket.org/circuits/circuits/src/tip/examples/telnet.py>`_
+The `telnet Example <https://github.com/circuits/circuits/tree/master/examples/telnet.py>`_
 does this for example.
diff --git a/docs/source/man/misc/tools.rst b/docs/source/man/misc/tools.rst
@@ -92,7 +92,7 @@ and by called ``<name>.png`` where **<name>** is the name of
 the top-level component in your application of the value you pass
 to the ``name=`` keyword argument of ``~circuits.tools.graph``.
 
-Example output of `telnet Example <https://bitbucket.org/circuits/circuits/src/tip/examples/telnet.py>`_:
+Example output of `telnet Example <https://github.com/circuits/circuits/tree/master/examples/telnet.py>`_:
 
 .. image:: ../examples/Telnet.png
 

diff --git a/docs/source/roadmap.rst b/docs/source/roadmap.rst
@@ -1,23 +1,6 @@
 Road Map
 ========
 
+We managed our Roadmap on our [Github Project](https://github.com/circuits/circuits)
 
-Here's a list of upcoming releases of circuits in order of "next release
-first".
-
-Each bullet point states a high level goal we're trying to achieve for
-the release whilst the "Issues List" (*linked to our Issue Tracker*)
-lists specific issues we've tagged with the respective milestone.
-
-.. note:: At this stage we don't have any good estimates for our milestones
-          but we hope we can improve this with future releases and start
-          adding estimates here.
-
-
-circuits 3.1
-------------
-
-- Improved `circuits.web <http://circuitsweb.com>`_
-
-
-.. seealso:: `circuits 3.1 milestone <https://bitbucket.org/circuits/circuits/issues?milestone=3.1&status=open&status=new>`_
+.. see:: [Milestones](https://github.com/circuits/circuits/milestones)
diff --git a/docs/source/start/downloading.rst b/docs/source/start/downloading.rst
@@ -6,21 +6,20 @@ Latest Stable Release
 ---------------------
 
 The latest stable releases can be downloaded from the
-`Downloads <http://bitbucket.org/circuits/circuits/downloads/>`_ page
+`Releases <https://github.com/circuits/circuits/releases>`_ page
 (*specifically the Tags tab*).
 
 
 Latest Development Source Code
 ------------------------------
 
-We use `Mercurial <http://mercurial.selenic.com/>`_ for source control
-and code sharing.
+We use `Git <https://git-scm.com/>`_ for source control and code sharing.
 
 The latest development branch can be cloned using the following command:
 
 .. code-block:: sh
    
-   $ hg clone https://bitbucket.org/circuits/circuits/
+   $ git clone https://github.com/circuits/circuits.git
    
-For further instructions on how to use Mercurial, please refer to the
-`Mercurial Book <http://mercurial.selenic.com/wiki/MercurialBook>`_.
+For further instructions on how to use Git, please refer to the
+`Git Website <https://git-scm.com/>`_.
diff --git a/docs/source/tutorials/telnet/index.rst b/docs/source/tutorials/telnet/index.rst
@@ -9,7 +9,7 @@ Overview
 --------
 
 Welcome to our 2nd circuits tutorial. This tutorial is going to walk you
-through the `telnet Example <https://bitbucket.org/circuits/circuits/src/tip/examples/telnet.py>`_
+through the `telnet Example <https://github.com/circuits/circuits/tree/master/examples/telnet.py>`_
 showing you how to various parts of the circuits component library for
 building a simple TCP client that also accepts user input.
 
@@ -166,7 +166,7 @@ Testing
 -------
 
 To try this example out, download a copy of the
-`echoserver Example <https://bitbucket.org/circuits/circuits/src/tip/echoserver.py>`_
+`echoserver Example <https://github.com/circuits/circuits/tree/master/echoserver.py>`_
 and copy and paste the full source code of the
 ``Telnet`` example above into a file called ``telnet.py``.
 
@@ -180,7 +180,7 @@ In a second terminal run::
 
 Have fun!
 
-For more examples see `examples <https://bitbucket.org/circuits/circuits/src/tip/examples>`_.
+For more examples see `examples <https://github.com/circuits/circuits/tree/master/examples>`_.
 
 .. seealso::
     - :doc:`../../faq`

diff --git a/docs/source/web/howtos.rst b/docs/source/web/howtos.rst
@@ -155,7 +155,7 @@ trivial example:
     WebSockets("/websocket").register(app)
     app.run()
 
-See the `circuits.web examples <https://bitbucket.org/circuits/circuits/src/tip/examples/web>`_.
+See the `circuits.web examples <https://github.com/circuits/circuits/tree/master/examples/web>`_.
 
 
 How do I: Build a Simple Form