Added description text to 'channel.join' docs, fixed exposed markup in docs. (#147)

* Added description text to 'channel.join' docs

* Removed unneeded '..code-block' tags...

* Added '..code-block' tags, but correctly this time...

* Added highlight languages to code-block tags in README

* Added highlight languages to code-block tags in README, this time with proper newlines.

* Fixed a typo in README

* Use more verbose code-block formatting

* Regenerated docs

Author: Roach

README.rst

@@ -52,7 +52,7 @@ If you get stuck, we’re here to help. The following are the best ways to get a
 Documentation
 --------------
 
-For a comprehensive method information and usage examples, see the `full documentation <http://slackapi.github.io/python-slackclient>`_.
+For comprehensive method information and usage examples, see the `full documentation <http://slackapi.github.io/python-slackclient>`_.
 
 Basic Usage
 ------------
@@ -71,7 +71,8 @@ The primary use of Slack is sending messages. Whether you're sending a message
 to a user or to a channel, this method handles both.
 
 To send a message to a channel, use the channel's ID. For IMs, use the user's ID.
-.. code-block::
+
+.. code-block:: python
 
   from slackclient import SlackClient
 
@@ -91,7 +92,8 @@ page for a full list of formatting and authorship options.
 Deleting a message
 ********************
 Sometimes you need to delete things.
-..code-block::
+
+.. code-block:: python
 
   from slackclient import SlackClient
 
@@ -112,7 +114,8 @@ You can quickly respond to any message on Slack with an emoji reaction. Reaction
 can be used for any purpose: voting, checking off to-do items, showing excitement — and just for fun.
 
 This method adds a reaction (emoji) to an item (``file``, ``file comment``, ``channel message``, ``group message``, or ``direct message``). One of file, file_comment, or the combination of channel and timestamp must be specified.
-..code-block::
+
+.. code-block:: python
 
   from slackclient import SlackClient
 
@@ -127,7 +130,8 @@ This method adds a reaction (emoji) to an item (``file``, ``file comment``, ``ch
   )
 
 Removing an emoji reaction is basically the same format, but you'll use ``reactions.remove`` instead of ``reactions.add``
-..code-block::
+
+.. code-block:: python
 
   sc.api_call(
     "reactions.remove",
@@ -144,7 +148,8 @@ Getting a list of channels
 At some point, you'll want to find out what channels are available to your app. This is how you get that list.
 
 **Note:** This call requires the ``channels:read`` scope.
-..code-block::
+
+.. code-block:: python
 
   from slackclient import SlackClient
 
@@ -155,7 +160,7 @@ At some point, you'll want to find out what channels are available to your app.
 
 Archived channels are included by default. You can exclude them by passing ``exclude_archived=1`` to your request.
 
-::
+.. code-block:: python
 
   from slackclient import SlackClient
 
@@ -172,7 +177,8 @@ See `channels.list <https://api.slack.com/methods/channels.list>`_ for more info
 Getting a channel's info
 *************************
 Once you have the ID for a specific channel, you can fetch information about that channel.
-..code-block::
+
+.. code-block:: python
 
   from slackclient import SlackClient
 
@@ -188,7 +194,9 @@ See `channels.info <https://api.slack.com/methods/channels.info>`_ for more info
 
 Joining a channel
 ********************
-..code-block::
+Channels are the social hub of most Slack teams. Here's how you hop into one:
+
+.. code-block:: python
 
   from slackclient import SlackClient
 
@@ -201,15 +209,16 @@ Joining a channel
   )
 
 If you are already in the channel, the response is slightly different.
-``already_in_channel`` will be true, and a limited ``channel`` object will be returned.
+``already_in_channel`` will be true, and a limited ``channel`` object will be returned. Bot users cannot join a channel on their own, they need to be invited by another user.
 
 See `channels.join <https://api.slack.com/methods/channels.join>`_ for more info.
 
 Leaving a channel
 ********************
 Maybe you've finished up all the business you had in a channel, or maybe you
 joined one by accident. This is how you leave a channel.
-..code-block::
+
+.. code-block:: python
 
   from slackclient import SlackClient
 
@@ -225,4 +234,4 @@ See `channels.leave <https://api.slack.com/methods/channels.leave>`_ for more in
 
 Additional Information
 ********************************************************************************************
-For a comprehensive method information and usage examples, see the `full documentation`_.
+For comprehensive method information and usage examples, see the `full documentation`_.

docs-src/auth.rst

@@ -8,17 +8,20 @@ Handling tokens and other sensitive data
 Slack tokens are the keys to your—or your customers’—teams. Keep them secret. Keep them safe. One way to do that is to never explicitly hardcode them.
 
 Try to avoid this when possible:
-::
+
+.. code-block:: python
 
   token = 'xoxb-abc-1232'
 
 If you commit this code to GitHub, the world gains access to this token’s team. Rather, we recommend you pass tokens in as environment variables, or persist them in a database that is accessed at runtime. You can add a token to the environment by starting your app as:
-::
+
+.. code-block:: python
 
   SLACK_BOT_TOKEN="xoxb-abc-1232" python myapp.py
 
 Then in your code retrieve the key with:
-::
+
+.. code-block:: python
 
   import os
   SLACK_BOT_TOKEN = os.environ["SLACK_BOT_TOKEN"]
@@ -48,7 +51,8 @@ In order to implement OAuth in your app, you will need to include a web server.
 As mentioned above, we're setting the app tokens and other configs in environment variables and pulling them into global variables.
 
 Depending on what actions your app will need to perform, you'll need different OAuth permission scopes. Review the available scopes `here <https://api.slack.com/docs/oauth-scopes>`_.
-::
+
+.. code-block:: python
 
   import os
   from flask import Flask, request
@@ -67,7 +71,8 @@ This directs the user to Slack's OAuth acceptance page, where the user will revi
 or refuse the permissions your app is requesting as defined by the requested scope(s).
 
 For the best user experience, use the `Add to Slack button <https://api.slack.com/docs/slack-button>`_ to direct users to approve your application for access or `Sign in with Slack <https://api.slack.com/docs/sign-in-with-slack>`_ to log users in.
-::
+
+.. code-block:: python
 
   @app.route("/begin_auth", methods=["GET"])
   def pre_install():
@@ -89,7 +94,7 @@ which do not require a token. ``oauth.access`` is one example of this. Since thi
 is the endpoint you'll use to retrieve the tokens for later API requests,
 an empty string ``""`` is acceptable for this request.
 
-::
+.. code-block:: python
 
   @app.route("/finish_auth", methods=["GET", "POST"])
   def post_install():
@@ -121,7 +126,7 @@ user, within the context of the approving team.
 When you use Web API methods on behalf of your bot user, you should use this bot
 user access token instead of the top-level access token granted to your application.
 
-::
+.. code-block:: python
 
     # Save the bot token to an environmental variable or to your data store
     # for later use

docs-src/basic_usage.rst

@@ -20,7 +20,8 @@ The primary use of Slack is sending messages. Whether you're sending a message
 to a user or to a channel, this method handles both.
 
 To send a message to a channel, use the channel's ID. For IMs, use the user's ID.
-::
+
+.. code-block:: python
 
   from slackclient import SlackClient
 
@@ -44,7 +45,8 @@ Updating the content of a message
 Let's say you have a bot which posts the status of a request. When that request
 is updated, you'll want to update the message to reflect it's state. Or your user
 might want to fix a typo or change some wording. This is how you'll make those changes.
-::
+
+.. code-block:: python
 
   from slackclient import SlackClient
 
@@ -66,7 +68,8 @@ and some special considerations when calling this with a bot user.
 Deleting a message
 -------------------
 Sometimes you need to delete things.
-::
+
+.. code-block:: python
 
   from slackclient import SlackClient
 
@@ -89,7 +92,8 @@ You can quickly respond to any message on Slack with an emoji reaction. Reaction
 can be used for any purpose: voting, checking off to-do items, showing excitement — and just for fun.
 
 This method adds a reaction (emoji) to an item (``file``, ``file comment``, ``channel message``, ``group message``, or ``direct message``). One of file, file_comment, or the combination of channel and timestamp must be specified.
-::
+
+.. code-block:: python
 
   from slackclient import SlackClient
 
@@ -104,7 +108,8 @@ This method adds a reaction (emoji) to an item (``file``, ``file comment``, ``ch
   )
 
 Removing an emoji reaction is basically the same format, but you'll use ``reactions.remove`` instead of ``reactions.add``
-::
+
+.. code-block:: python
 
   sc.api_call(
     "reactions.remove",
@@ -123,7 +128,8 @@ Getting a list of channels
 At some point, you'll want to find out what channels are available to your app. This is how you get that list.
 
 **Note:** This call requires the ``channels:read`` scope.
-::
+
+.. code-block:: python
 
   from slackclient import SlackClient
 
@@ -134,7 +140,8 @@ At some point, you'll want to find out what channels are available to your app.
 
 Archived channels are included by default. You can exclude them by passing ``exclude_archived=1`` to your request.
 
-::
+
+.. code-block:: python
 
   from slackclient import SlackClient
 
@@ -153,7 +160,8 @@ See `channels.list <https://api.slack.com/methods/channels.list>`_ for more info
 Getting a channel's info
 -------------------------
 Once you have the ID for a specific channel, you can fetch information about that channel.
-::
+
+.. code-block:: python
 
   from slackclient import SlackClient
 
@@ -171,7 +179,9 @@ See `channels.info <https://api.slack.com/methods/channels.info>`_ for more info
 
 Joining a channel
 ------------------
-::
+Channels are the social hub of most Slack teams. Here's how you hop into one:
+
+.. code-block:: python
 
   from slackclient import SlackClient
 
@@ -184,7 +194,7 @@ Joining a channel
   )
 
 If you are already in the channel, the response is slightly different.
-``already_in_channel`` will be true, and a limited ``channel`` object will be returned.
+``already_in_channel`` will be true, and a limited ``channel`` object will be returned. Bot users cannot join a channel on their own, they need to be invited by another user.
 
 See `channels.join <https://api.slack.com/methods/channels.join>`_ for more info.
 
@@ -194,7 +204,8 @@ Leaving a channel
 ------------------
 Maybe you've finished up all the business you had in a channel, or maybe you
 joined one by accident. This is how you leave a channel.
-::
+
+.. code-block:: python
 
   from slackclient import SlackClient
 
@@ -212,7 +223,8 @@ See `channels.leave <https://api.slack.com/methods/channels.leave>`_ for more in
 
 Get a list of team members
 ------------------------------
-::
+
+.. code-block:: python
 
   from slackclient import SlackClient
 

docs-src/faq.rst

@@ -52,13 +52,13 @@ This project's documentation is generated with `Sphinx <http://www.sphinx-doc.or
 reStructuredText files in the ``docs-src`` folder, you'll need to rebuild the documentation. First, install the project's
 development dependencies (ideally using `virtualenv <https://virtualenv.pypa.io>`_.
 
-::
+.. code-block:: bash
 
   pip install -r requirements.txt -r requirements-dev.text
 
 Then run Sphinx.
 
-::
+.. code-block:: bash
 
   sphinx-build -c ./docs-src/_themes/slack/ -b html docs-src docs
 

docs/basic_usage.html

@@ -116,7 +116,7 @@
 <span id="web-api-examples"></span><h1>Basic Usage<a class="headerlink" href="#basic-usage" title="Permalink to this headline">¶</a></h1>
 <p>The Slack Web API allows you to build applications that interact with Slack in more complex ways than the integrations
 we provide out of the box.</p>
-<p>This package is a modular wrapper designed to make Slack <a class="reference external" href="https://api.slack.com/web">Web API</a> calls simpler and easier for your
+<p>This package is a modular wrapper designed to make Slack <a href="#id1"><span class="problematic" id="id2">`Web API`_</span></a> calls simpler and easier for your
 app. Provided below are examples of how to interact with commonly used API endpoints, but this is by no means
 a complete list. Review the full list of available methods <a class="reference external" href="https://api.slack.com/methods">here</a>.</p>
 <p>See <a class="reference internal" href="auth.html#handling-tokens"><span class="std std-ref">Tokens &amp; Authentication</span></a> for API token handling best practices.</p>
@@ -259,19 +259,20 @@ <h2>Getting a channel&#8217;s info<a class="headerlink" href="#getting-a-channel
 <hr class="docutils" />
 <div class="section" id="joining-a-channel">
 <h2>Joining a channel<a class="headerlink" href="#joining-a-channel" title="Permalink to this headline">¶</a></h2>
+<p>Channels are the social hub of most Slack teams. Here&#8217;s how you hop into one:</p>
 <div class="highlight-python"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">slackclient</span> <span class="kn">import</span> <span class="n">SlackClient</span>
 
 <span class="n">slack_token</span> <span class="o">=</span> <span class="n">os</span><span class="o">.</span><span class="n">environ</span><span class="p">[</span><span class="s2">&quot;SLACK_API_TOKEN&quot;</span><span class="p">]</span>
 <span class="n">sc</span> <span class="o">=</span> <span class="n">SlackClient</span><span class="p">(</span><span class="n">slack_token</span><span class="p">)</span>
 
 <span class="n">sc</span><span class="o">.</span><span class="n">api_call</span><span class="p">(</span>
-  <span class="s2">&quot;channels.info&quot;</span><span class="p">,</span>
+  <span class="s2">&quot;channels.join&quot;</span><span class="p">,</span>
   <span class="n">channel</span><span class="o">=</span><span class="s2">&quot;C0XXXXXXY&quot;</span>
 <span class="p">)</span>
 </pre></div>
 </div>
 <p>If you are already in the channel, the response is slightly different.
-<code class="docutils literal"><span class="pre">already_in_channel</span></code> will be true, and a limited <code class="docutils literal"><span class="pre">channel</span></code> object will be returned.</p>
+<code class="docutils literal"><span class="pre">already_in_channel</span></code> will be true, and a limited <code class="docutils literal"><span class="pre">channel</span></code> object will be returned. Bot users cannot join a channel on their own, they need to be invited by another user.</p>
 <p>See <a class="reference external" href="https://api.slack.com/methods/channels.join">channels.join</a> for more info.</p>
 </div>
 <hr class="docutils" />

docs/faq.html

@@ -154,11 +154,11 @@ <h2>How do I compile the documentation?<a class="headerlink" href="#how-do-i-com
 <p>This project&#8217;s documentation is generated with <a class="reference external" href="http://www.sphinx-doc.org">Sphinx</a>. If you are editing one of the many
 reStructuredText files in the <code class="docutils literal"><span class="pre">docs-src</span></code> folder, you&#8217;ll need to rebuild the documentation. First, install the project&#8217;s
 development dependencies (ideally using <a class="reference external" href="https://virtualenv.pypa.io">virtualenv</a>.</p>
-<div class="highlight-python"><div class="highlight"><pre><span></span><span class="n">pip</span> <span class="n">install</span> <span class="o">-</span><span class="n">r</span> <span class="n">requirements</span><span class="o">.</span><span class="n">txt</span> <span class="o">-</span><span class="n">r</span> <span class="n">requirements</span><span class="o">-</span><span class="n">dev</span><span class="o">.</span><span class="n">text</span>
+<div class="highlight-bash"><div class="highlight"><pre><span></span>pip install -r requirements.txt -r requirements-dev.text
 </pre></div>
 </div>
 <p>Then run Sphinx.</p>
-<div class="highlight-python"><div class="highlight"><pre><span></span><span class="n">sphinx</span><span class="o">-</span><span class="n">build</span> <span class="o">-</span><span class="n">c</span> <span class="o">./</span><span class="n">docs</span><span class="o">-</span><span class="n">src</span><span class="o">/</span><span class="n">_themes</span><span class="o">/</span><span class="n">slack</span><span class="o">/</span> <span class="o">-</span><span class="n">b</span> <span class="n">html</span> <span class="n">docs</span><span class="o">-</span><span class="n">src</span> <span class="n">docs</span>
+<div class="highlight-bash"><div class="highlight"><pre><span></span>sphinx-build -c ./docs-src/_themes/slack/ -b html docs-src docs
 </pre></div>
 </div>
 <p>Do be sure to add the <code class="docutils literal"><span class="pre">docs</span></code> folder and its contents to your pull request!</p>