Merge pull request #1599 from LilSpazJoekp/reformatting_fixes

Format documentation
praw-dev · Feb 25, 2021 · abbcaac · abbcaac
2 parents f782c4a + d7c9e8a
commit abbcaac
Show file tree

Hide file tree

Showing 169 changed files with 1,755 additions and 1,861 deletions.
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -30,10 +30,10 @@ jobs:
       run: python ./tools/static_word_checks.py
     - name: Check documentation
       run: python ./tools/check_documentation.py
-    - name: Check docstrings
-      run: python ./tools/check_docstring.py
     - name: Run black
       run: black --check --verbose .
+    - name: Run docstrfmt
+      run: docstrfmt -cvp pyproject.toml -e "docs/examples/*" .
     - name: Run flake8
       run: flake8 --exclude docs --statistics
     - name: Run flynt
@@ -71,7 +71,6 @@ jobs:
     strategy:
       matrix:
         os: [macOS-latest, ubuntu-latest, windows-latest]
-
   test-multi-python:
     name: Test Python ${{ matrix.python-version }}
     runs-on: ubuntu-latest

diff --git a/AUTHORS.rst b/AUTHORS.rst
@@ -5,7 +5,6 @@ Maintainers
 - Joe RH <jarhill0@gmail.com> `@jarhill0 <https://github.com/jarhill0>`_
 - Joel Payne <lilspazjoekp@gmail.com> `@LilSpazJoekp <https://github.com/LilSpazJoekp>`_
 
-
 Documentation Contributors
 ==========================
 
@@ -26,13 +25,11 @@ Documentation Contributors
 
 <!-- - Add "Name <email (optional)> and github profile link" above this line. -->
 
-
 Logo Creator
 ============
 
 - kungming2 `@kungming2 <https://github.com/kungming2>`_
 
-
 Source Contributors
 ===================
 
@@ -51,9 +48,11 @@ Source Contributors
 - Andrew Arnold `@asquared31415 <https://github.com/asquared31415>`_
 - bakonydraco `@bakonydraco <https://github.com/bakonydraco>`_
 - salehio `@salehio <https://github.com/salehio>`_
-- Amanda O'Neal <amanda.oneal.dev@gmail.com> `@amandaoneal <https://github.com/amandaoneal>`_
+- Amanda O'Neal <amanda.oneal.dev@gmail.com> `@amandaoneal
+  <https://github.com/amandaoneal>`_
 - Gourari Oussama <gourari.ouss@gmail.com> `@O-Gourari <https://github.com/O-Gourari>`_
-- Declan Hoare <declanhoare@exemail.com.au> `@NetwideRogue <https://github.com/NetwideRogue>`_
+- Declan Hoare <declanhoare@exemail.com.au> `@NetwideRogue
+  <https://github.com/NetwideRogue>`_
 - Elaina Martineau `@CrackedP0t <https://github.com/CrackedP0t>`_
 - Rob Curtis <BourbonInExile@gmail.com> `@waab76 <https://github.com/waab76>`_
 - Pyprohly <pyprohly@outlook.com> `@Pyprohly <https://github.com/Pyprohly>`_
@@ -64,7 +63,8 @@ Source Contributors
 - Jack Steel `@jackodsteel <https://github.com/jackodsteel>`_
 - David Mirch `@fwump38 <https://github.com/fwump38>`_
 - PythonCoderAS `@PythonCoderAS <https://github.com/PythonCoderAS>`_
-- Michael Cetrulo <contact@michael-cetrulo.com> `@git2samus <https://github.com/git2samus>`_
+- Michael Cetrulo <contact@michael-cetrulo.com> `@git2samus
+  <https://github.com/git2samus>`_
 - George Schizas `@gschizas <https://github.com/gschizas>`_
 - Todd Roberts `@toddrob99 <https://github.com/toddrob99>`_
 - MaybeNetwork `@MaybeNetwork <https://github.com/MaybeNetwork>`_

diff --git a/CHANGES.rst b/CHANGES.rst
diff --git a/README.rst b/README.rst
@@ -2,91 +2,99 @@ PRAW: The Python Reddit API Wrapper
 ===================================
 
 .. image:: https://img.shields.io/pypi/v/praw.svg
-   :alt: Latest PRAW Version
-   :target: https://pypi.python.org/pypi/praw
+    :alt: Latest PRAW Version
+    :target: https://pypi.python.org/pypi/praw
+
 .. image:: https://img.shields.io/pypi/pyversions/praw
-   :alt: Supported Python Versions
-   :target: https://pypi.python.org/pypi/praw
+    :alt: Supported Python Versions
+    :target: https://pypi.python.org/pypi/praw
+
 .. image:: https://img.shields.io/pypi/dm/praw
-   :alt: PyPI - Downloads - Monthly
-   :target: https://pypi.python.org/pypi/praw
+    :alt: PyPI - Downloads - Monthly
+    :target: https://pypi.python.org/pypi/praw
+
 .. image:: https://coveralls.io/repos/github/praw-dev/praw/badge.svg?branch=master
-   :alt: Coveralls Coverage
-   :target: https://coveralls.io/github/praw-dev/praw?branch=master
+    :alt: Coveralls Coverage
+    :target: https://coveralls.io/github/praw-dev/praw?branch=master
+
 .. image:: https://github.com/praw-dev/praw/workflows/CI/badge.svg
-   :alt: Github Actions Coverage
-   :target: https://github.com/praw-dev/praw/actions?query=branch%3Amaster
+    :alt: Github Actions Coverage
+    :target: https://github.com/praw-dev/praw/actions?query=branch%3Amaster
+
 .. image:: https://img.shields.io/badge/Contributor%20Covenant-v2.0%20adopted-ff69b4.svg
-   :alt: Contributor Covenant
-   :target: https://github.com/praw-dev/praw/blob/master/CODE_OF_CONDUCT.md
-
-PRAW, an acronym for "Python Reddit API Wrapper", is a Python package that
-allows for simple access to Reddit's API. PRAW aims to be easy to use and
-internally follows all of `Reddit's API rules
-<https://github.com/reddit/reddit/wiki/API>`_. With PRAW there's no need to
-introduce ``sleep`` calls in your code. Give your client an appropriate user
+    :alt: Contributor Covenant
+    :target: https://github.com/praw-dev/praw/blob/master/CODE_OF_CONDUCT.md
+
+PRAW, an acronym for "Python Reddit API Wrapper", is a Python package that allows for
+simple access to Reddit's API. PRAW aims to be easy to use and internally follows all of
+`Reddit's API rules <https://github.com/reddit/reddit/wiki/API>`_. With PRAW there's no
+need to introduce ``sleep`` calls in your code. Give your client an appropriate user
 agent and you're set.
 
 .. _installation:
 
 Installation
 ------------
 
-PRAW is supported on Python 3.6+. The recommended way to
-install PRAW is via `pip <https://pypi.python.org/pypi/pip>`_.
+PRAW is supported on Python 3.6+. The recommended way to install PRAW is via `pip
+<https://pypi.python.org/pypi/pip>`_.
 
 .. code-block:: bash
 
-   pip install praw
+    pip install praw
 
 To install the latest development version of PRAW run the following instead:
 
 .. code-block:: bash
 
-   pip install --upgrade https://github.com/praw-dev/praw/archive/master.zip
+    pip install --upgrade https://github.com/praw-dev/praw/archive/master.zip
 
-For instructions on installing Python and pip see "The Hitchhiker's Guide to
-Python" `Installation Guides
-<https://docs.python-guide.org/en/latest/starting/installation/>`_.
+For instructions on installing Python and pip see "The Hitchhiker's Guide to Python"
+`Installation Guides <https://docs.python-guide.org/en/latest/starting/installation/>`_.
 
 Quickstart
 ----------
 
-Assuming you already have a credentials for a script-type OAuth application you
-can instantiate an instance of PRAW like so:
+Assuming you already have a credentials for a script-type OAuth application you can
+instantiate an instance of PRAW like so:
 
 .. code-block:: python
 
-  import praw
-  reddit = praw.Reddit(client_id="CLIENT_ID", client_secret="CLIENT_SECRET",
-                       password="PASSWORD", user_agent="USERAGENT",
-                       username="USERNAME")
+    import praw
+
+    reddit = praw.Reddit(
+        client_id="CLIENT_ID",
+        client_secret="CLIENT_SECRET",
+        password="PASSWORD",
+        user_agent="USERAGENT",
+        username="USERNAME",
+    )
 
 With the ``reddit`` instance you can then interact with Reddit:
 
 .. code-block:: python
 
-  # Create a submission to r/test
-  reddit.subreddit("test").submit("Test Submission", url="https://reddit.com")
+    # Create a submission to r/test
+    reddit.subreddit("test").submit("Test Submission", url="https://reddit.com")
 
-  # Comment on a known submission
-  submission = reddit.submission(url="https://www.reddit.com/comments/5e1az9")
-  submission.reply("Super rad!")
+    # Comment on a known submission
+    submission = reddit.submission(url="https://www.reddit.com/comments/5e1az9")
+    submission.reply("Super rad!")
 
-  # Reply to the first comment of a weekly top thread of a moderated community
-  submission = next(reddit.subreddit("mod").top("week"))
-  submission.comments[0].reply("An automated reply")
+    # Reply to the first comment of a weekly top thread of a moderated community
+    submission = next(reddit.subreddit("mod").top("week"))
+    submission.comments[0].reply("An automated reply")
 
-  # Output score for the first 256 items on the frontpage
-  for submission in reddit.front.hot(limit=256):
-      print(submission.score)
+    # Output score for the first 256 items on the frontpage
+    for submission in reddit.front.hot(limit=256):
+        print(submission.score)
 
-  # Obtain the moderator listing for r/redditdev
-  for moderator in reddit.subreddit("redditdev").moderator():
-      print(moderator)
+    # Obtain the moderator listing for r/redditdev
+    for moderator in reddit.subreddit("redditdev").moderator():
+        print(moderator)
 
-Please see PRAW's `documentation <https://praw.readthedocs.io/>`_ for
-more examples of what you can do with PRAW.
+Please see PRAW's `documentation <https://praw.readthedocs.io/>`_ for more examples of
+what you can do with PRAW.
 
 Discord Bots and Asynchronous Environments
 ------------------------------------------
@@ -111,17 +119,18 @@ PRAW related questions. This subreddit is for all Reddit API related discussion
 please tag submissions with *[PRAW]*. Please perform a search on the subreddit first to
 see if anyone has similar questions.
 
-Real-time chat can be conducted via the `PRAW Slack Organization <https://join.slack.com/t/praw/shared_invite/enQtOTUwMDcxOTQ0NzY5LWVkMGQ3ZDk5YmQ5MDEwYTZmMmJkMTJkNjBkNTY3OTU0Y2E2NGRlY2ZhZTAzMWZmMWRiMTMwYjdjODkxOGYyZjY>`_ (please create an issue if that invite link
-has expired).
+Real-time chat can be conducted via the `PRAW Slack Organization
+<https://join.slack.com/t/praw/shared_invite/enQtOTUwMDcxOTQ0NzY5LWVkMGQ3ZDk5YmQ5MDEwYTZmMmJkMTJkNjBkNTY3OTU0Y2E2NGRlY2ZhZTAzMWZmMWRiMTMwYjdjODkxOGYyZjY>`_
+(please create an issue if that invite link has expired).
 
 Please do not directly message any of the contributors via Reddit, email, or Slack
 unless they have indicated otherwise. We strongly encourage everyone to help others with
 their questions.
 
-Please file bugs and feature requests as issues on `GitHub <https://github.com/praw-
-dev/praw/issues>`_ after first searching to ensure a similar issue was not already
-filed. If such an issue already exists please give it a thumbs up reaction. Comments to
-issues containing additional information are certainly welcome.
+Please file bugs and feature requests as issues on `GitHub
+<https://github.com/praw-dev/praw/issues>`_ after first searching to ensure a similar
+issue was not already filed. If such an issue already exists please give it a thumbs up
+reaction. Comments to issues containing additional information are certainly welcome.
 
 .. note::
 
@@ -151,21 +160,20 @@ Bryce Boe took over as maintainer of the ``reddit`` package.
 
 `June 2012
 <https://github.com/praw-dev/praw/commit/adaf89fe8631f41ab9913b379de104c9ef6a1e73>`_:
-Bryce renamed the project ``PRAW`` and the repository was relocated to the
-newly created praw-dev organization on GitHub.
+Bryce renamed the project ``PRAW`` and the repository was relocated to the newly created
+praw-dev organization on GitHub.
 
 `February 2016
 <https://github.com/praw-dev/praw/commit/252083ef1dbfe6ea53c2dc99ac235b4ba330b658>`_:
 Bryce began work on PRAW4, a complete rewrite of PRAW.
 
-
 License
 -------
 
 PRAW's source (v4.0.0+) is provided under the `Simplified BSD License
 <https://github.com/praw-dev/praw/blob/0860c11a9309c80621c267af7caeb6a993933744/LICENSE.txt>`_.
 
-* Copyright ©, 2016, Bryce Boe
+- Copyright ©, 2016, Bryce Boe
 
 Earlier versions of PRAW were released under `GPLv3
 <https://github.com/praw-dev/praw/blob/0c88697fdc26e75f87b68e2feb11e101e90ce215/COPYING>`_.
diff --git a/docs/code_overview/exceptions.rst b/docs/code_overview/exceptions.rst
@@ -2,12 +2,12 @@ Exceptions in PRAW
 ==================
 
 In addition to exceptions under the ``praw.exceptions`` namespace shown below,
-exceptions might be raised that inherit from ``prawcore.PrawcoreException``.
-Please see the following resource for information on those exceptions:
+exceptions might be raised that inherit from ``prawcore.PrawcoreException``. Please see
+the following resource for information on those exceptions:
 https://github.com/praw-dev/prawcore/blob/master/prawcore/exceptions.py
 
 praw.exceptions
 ---------------
 
 .. automodule:: praw.exceptions
-   :inherited-members:
+    :inherited-members:
diff --git a/docs/code_overview/models/comment.rst b/docs/code_overview/models/comment.rst
@@ -2,6 +2,6 @@ Comment
 =======
 
 .. autoclass:: praw.models.Comment
-   :inherited-members:
+    :inherited-members:
 
 .. include:: note_dynamically_provided_attributes.txt
diff --git a/docs/code_overview/models/livethread.rst b/docs/code_overview/models/livethread.rst
@@ -2,6 +2,6 @@ LiveThread
 ==========
 
 .. autoclass:: praw.models.LiveThread
-   :inherited-members:
+    :inherited-members:
 
 .. include:: note_dynamically_provided_attributes.txt
diff --git a/docs/code_overview/models/liveupdate.rst b/docs/code_overview/models/liveupdate.rst
@@ -2,6 +2,6 @@ LiveUpdate
 ==========
 
 .. autoclass:: praw.models.LiveUpdate
-   :inherited-members:
+    :inherited-members:
 
 .. include:: note_dynamically_provided_attributes.txt
diff --git a/docs/code_overview/models/message.rst b/docs/code_overview/models/message.rst
@@ -2,6 +2,6 @@ Message
 =======
 
 .. autoclass:: praw.models.Message
-   :inherited-members:
+    :inherited-members:
 
 .. include:: note_dynamically_provided_attributes.txt
diff --git a/docs/code_overview/models/modmailconversation.rst b/docs/code_overview/models/modmailconversation.rst
@@ -2,6 +2,6 @@ ModmailConversation
 ===================
 
 .. autoclass:: praw.models.reddit.modmail.ModmailConversation
-   :inherited-members:
+    :inherited-members:
 
 .. include:: note_dynamically_provided_attributes.txt
diff --git a/docs/code_overview/models/more.rst b/docs/code_overview/models/more.rst
@@ -2,6 +2,6 @@ MoreComments
 ============
 
 .. autoclass:: praw.models.MoreComments
-   :inherited-members:
+    :inherited-members:
 
 .. include:: note_dynamically_provided_attributes.txt
diff --git a/docs/code_overview/models/multireddit.rst b/docs/code_overview/models/multireddit.rst
@@ -2,6 +2,6 @@ Multireddit
 ===========
 
 .. autoclass:: praw.models.Multireddit
-   :inherited-members:
+    :inherited-members:
 
 .. include:: note_dynamically_provided_attributes.txt
diff --git a/docs/code_overview/models/redditor.rst b/docs/code_overview/models/redditor.rst
@@ -2,6 +2,6 @@ Redditor
 ========
 
 .. autoclass:: praw.models.Redditor
-   :inherited-members:
+    :inherited-members:
 
 .. include:: note_dynamically_provided_attributes.txt
diff --git a/docs/code_overview/models/submission.rst b/docs/code_overview/models/submission.rst
@@ -2,6 +2,6 @@ Submission
 ==========
 
 .. autoclass:: praw.models.Submission
-   :inherited-members:
+    :inherited-members:
 
 .. include:: note_dynamically_provided_attributes.txt
diff --git a/docs/code_overview/models/subreddit.rst b/docs/code_overview/models/subreddit.rst
@@ -2,6 +2,6 @@ Subreddit
 =========
 
 .. autoclass:: praw.models.Subreddit
-   :inherited-members:
+    :inherited-members:
 
 .. include:: note_dynamically_provided_attributes.txt
diff --git a/docs/code_overview/models/wikipage.rst b/docs/code_overview/models/wikipage.rst
@@ -2,6 +2,6 @@ WikiPage
 ========
 
 .. autoclass:: praw.models.reddit.wikipage.WikiPage
-   :inherited-members:
+    :inherited-members:
 
 .. include:: note_dynamically_provided_attributes.txt