[V3 Docs] Remove all build warnings (#1640)

* Upgrade sphinx version to 1.7+

* Fix title overlines/underlines in autostart_systemd.rst

* Skip trying to document a method from discord.py

* Add escaped space after backtick

* Escape underscores (sphinx tries to interpret a hyperlink)

* Use fully qualified reference for class

* Fix reference in tunnel.py

* Remove python syntax highlighting in data_converter.py

For some reason sphinx couldn't lex these as python. Removing the highlighting seems like the logical solution for now, since if it wasn't being lexed, it wouldn't highlight anyway.

* Comment out static path since we're not using it right now

* Update sphinx version in docs requirements too

Would rather remove this duplication but RTD is a special snowflake

.readthedocs.yml

@@ -11,4 +11,4 @@ python:
   pip_install: true
   extra_requirements:
     - docs
-    - mongo
+    - mongo

docs/autostart_systemd.rst

@@ -1,12 +1,12 @@
 .. systemd service guide
 
-==========================
+==============================================
 Setting up auto-restart using systemd on Linux
-==========================
+==============================================
 
----------------------------
+-------------------------
 Creating the service file
----------------------------
+-------------------------
 
 Create the new service file:
 
@@ -33,9 +33,9 @@ Paste the following and replace all instances of :code:`username` with the usern
 
 Save and exit :code:`ctrl + O; enter; ctrl + x`
 
----------------------------
+---------------------------------
 Starting and enabling the service
----------------------------
+---------------------------------
 
 .. note:: This same file can be used to start as many instances of the bot as you wish, without creating more service files, just start and enable more services and add any bot instance name after the **@**
 

docs/conf.py

@@ -114,7 +114,7 @@ html_context = {
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
-html_static_path = ['_static']
+# html_static_path = ['_static']
 
 # Custom sidebar templates, must be a dictionary that maps document names
 # to template names.

docs/framework_bot.rst

@@ -11,6 +11,7 @@ RedBase
 
 .. autoclass:: RedBase
     :members:
+    :exclude-members: get_context
 
 Red
 ^^^

docs/requirements.txt

@@ -1,4 +1,4 @@
-sphinx==1.6.5
+sphinx>=1.7
 sphinxcontrib-asyncio
 sphinx_rtd_theme
 git+https://github.com/Rapptz/discord.py@rewrite#egg=discord.py[voice]

redbot/core/config.py

@@ -749,7 +749,7 @@ class Config:
 
         Returns
         -------
-        Group
+        `Group <redbot.core.config.Group>`
             The guild's Group object.
 
         """
@@ -767,7 +767,7 @@ class Config:
 
         Returns
         -------
-        Group
+        `Group <redbot.core.config.Group>`
             The channel's Group object.
 
         """
@@ -783,7 +783,7 @@ class Config:
 
         Returns
         -------
-        Group
+        `Group <redbot.core.config.Group>`
             The role's Group object.
 
         """
@@ -799,7 +799,7 @@ class Config:
 
         Returns
         -------
-        Group
+        `Group <redbot.core.config.Group>`
             The user's Group object.
 
         """
@@ -815,7 +815,7 @@ class Config:
 
         Returns
         -------
-        Group
+        `Group <redbot.core.config.Group>`
             The member's Group object.
         """
         return self._get_base_group(self.MEMBER, member.guild.id, member.id)
@@ -834,7 +834,7 @@ class Config:
 
         Returns
         -------
-        Group
+        `Group <redbot.core.config.Group>`
             The custom group's Group object.
         """
         return self._get_base_group(group_identifier, *identifiers)

redbot/core/utils/data_converter.py

@@ -47,15 +47,11 @@ class DataConverter:
             This should be a function which takes a single argument argument
             (the loaded JSON) and from it either
             returns or yields one or more `dict`
-            whose items are in the form:
-
-            .. code-block:: python
+            whose items are in the form::
 
                 {(SCOPE, *IDENTIFIERS): {(key_tuple): value}}
 
-            an example of a possible entry of that dict:
-
-            .. code-block:: python
+            an example of a possible entry of that dict::
 
                 {(Config.MEMBER, '133049272517001216', '78631113035100160'):
                     {('balance',): 9001}}
@@ -100,15 +96,11 @@ class DataConverter:
             This should be a dictionary of values to set.
             This is provided as an alternative
             to providing a file and conversion specification
-            the dictionary should be in the following format
-
-            .. code-block:: python
+            the dictionary should be in the following format::
 
                 {(SCOPE, *IDENTIFIERS): {(key_tuple): value}}`
 
-            an example of a possible entry of that dict:
-
-            .. code-block:: python
+            an example of a possible entry of that dict::
 
                 {(Config.MEMBER, '133049272517001216', '78631113035100160'):
                     {('balance',): 9001}}

redbot/core/utils/menus.py

@@ -2,7 +2,7 @@
 Original source of reaction-based menu idea from
 https://github.com/Lunar-Dust/Dusty-Cogs/blob/master/menu/menu.py
 
-Ported to Red V3 by Palm__ (https://github.com/palmtree5)
+Ported to Red V3 by Palm\_\_ (https://github.com/palmtree5)
 """
 import asyncio
 import discord

redbot/core/utils/tunnel.py

@@ -112,13 +112,13 @@ class Tunnel(metaclass=TunnelMeta):
             The message content
         embed: `discord.Embed`
             The embed to send
-        files: `List[discord.Files]`
+        files: `list` of `discord.File`
             A list of files to send.
-        
+
         Returns
         -------
         list of `discord.Message`
-            The `discord.Message`(s) sent as a result
+            The `discord.Message`\ (s) sent as a result
 
         Raises
         ------

setup.py

@@ -110,7 +110,7 @@ setup(
             'pytest>3', 'pytest-asyncio'
         ],
         'mongo': ['motor'],
-        'docs': ['sphinx==1.6.5', 'sphinxcontrib-asyncio', 'sphinx_rtd_theme'],
+        'docs': ['sphinx>=1.7', 'sphinxcontrib-asyncio', 'sphinx_rtd_theme'],
         'voice': ['red-lavalink>=0.0.4']
     }
 )