Structure PRAW's documentation better

Notable changes: * Getting started is a caption which contains a quick start * No longer use sphinx's automodule feature. This means each documented class has its own page, and the link to those classes are logically grouped. This should permit the removal of properties in cases where attributes would be appropriate.
praw-dev · Nov 25, 2016 · d94f04b · d94f04b
1 parent 4c6ec55
commit d94f04b
Show file tree

Hide file tree

Showing 50 changed files with 436 additions and 241 deletions.
diff --git a/CHANGES.rst b/CHANGES.rst
@@ -7,15 +7,15 @@ Change Log
 **Fixed**
 
 * :meth:`~praw.models.Auth.authorize` properly sets the session's
-   Authentication (thanks @williammck).
+  Authentication (thanks @williammck).
 
 4.0.0rc1 (2016/11/20)
 ---------------------
 
 PRAW 4 introduces significant breaking changes. The numerous changes are not
 listed here, only the feature removals. Please read through
-:doc:`/pages/getting_started` to help with updating your code to PRAW 4. If you
-require additional help please ask on `/r/redditdev
+:doc:`/getting_started/quick_start` to help with updating your code to
+PRAW 4. If you require additional help please ask on `/r/redditdev
 <https://www.reddit.com/r/redditdev>`_ or in the `praw-dev/praw
 <https://gitter.im/praw-dev/praw>`_ channel on gitter.
 

diff --git a/docs/code_overview/exceptions.rst b/docs/code_overview/exceptions.rst
@@ -0,0 +1,2 @@
+Exceptions in PRAW
+==================
diff --git a/docs/code_overview/models/comment.rst b/docs/code_overview/models/comment.rst
@@ -0,0 +1,5 @@
+Comment
+=======
+
+.. autoclass:: praw.models.Comment
+   :inherited-members:
diff --git a/docs/code_overview/models/livethread.rst b/docs/code_overview/models/livethread.rst
@@ -0,0 +1,5 @@
+LiveThread
+==========
+
+.. autoclass:: praw.models.LiveThread
+   :inherited-members:
diff --git a/docs/code_overview/models/message.rst b/docs/code_overview/models/message.rst
@@ -0,0 +1,5 @@
+Message
+=======
+
+.. autoclass:: praw.models.Message
+   :inherited-members:
diff --git a/docs/code_overview/models/more.rst b/docs/code_overview/models/more.rst
@@ -0,0 +1,5 @@
+MoreComments
+============
+
+.. autoclass:: praw.models.MoreComments
+   :inherited-members:
diff --git a/docs/code_overview/models/multireddit.rst b/docs/code_overview/models/multireddit.rst
@@ -0,0 +1,5 @@
+Multireddit
+===========
+
+.. autoclass:: praw.models.Multireddit
+   :inherited-members:
diff --git a/docs/code_overview/models/redditor.rst b/docs/code_overview/models/redditor.rst
@@ -0,0 +1,5 @@
+Redditor
+========
+
+.. autoclass:: praw.models.Redditor
+   :inherited-members:
diff --git a/docs/code_overview/models/submission.rst b/docs/code_overview/models/submission.rst
@@ -0,0 +1,5 @@
+Submission
+==========
+
+.. autoclass:: praw.models.Submission
+   :inherited-members:
diff --git a/docs/code_overview/models/subreddit.rst b/docs/code_overview/models/subreddit.rst
@@ -0,0 +1,5 @@
+Subreddit
+=========
+
+.. autoclass:: praw.models.Subreddit
+   :inherited-members:
diff --git a/docs/code_overview/models/wikipage.rst b/docs/code_overview/models/wikipage.rst
@@ -0,0 +1,5 @@
+WikiPage
+============
+
+.. autoclass:: praw.models.WikiPage
+   :inherited-members:
diff --git a/docs/code_overview/other.rst b/docs/code_overview/other.rst
@@ -0,0 +1,47 @@
+Other Classes
+=============
+
+The following list of classes are provided here for complete documentation. You
+should not likely need to work with these classes directly, but rather through
+instances of them bound to an attribute of one of the PRAW models.
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Flair Helpers
+
+   other/submissionflair
+   other/subredditflair
+   other/subredditflairtemplates
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Moderation Helpers
+
+   other/submissionmoderation
+   other/subredditmoderation
+   other/wikipagemoderation
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Relationship Helpers
+
+   other/contributorrelationship
+   other/moderatorrelationship
+   other/subredditrelationship
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Subreddit Helpers
+
+   other/subredditstream
+   other/subredditstylesheet
+   other/subredditwiki
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Others
+
+   other/auth
+   other/commentforest
+   other/domainlisting
+   other/subredditmessage
diff --git a/docs/code_overview/other/auth.rst b/docs/code_overview/other/auth.rst
@@ -0,0 +1,5 @@
+Auth
+====
+
+.. autoclass:: praw.models.Auth
+   :inherited-members:
diff --git a/docs/code_overview/other/commentforest.rst b/docs/code_overview/other/commentforest.rst
@@ -0,0 +1,5 @@
+CommentForest
+=============
+
+.. autoclass:: praw.models.comment_forest.CommentForest
+   :inherited-members:
diff --git a/docs/code_overview/other/contributorrelationship.rst b/docs/code_overview/other/contributorrelationship.rst
@@ -0,0 +1,5 @@
+ContributorRelationship
+=======================
+
+.. autoclass:: praw.models.reddit.subreddit.ContributorRelationship
+   :inherited-members:
diff --git a/docs/code_overview/other/domainlisting.rst b/docs/code_overview/other/domainlisting.rst
@@ -0,0 +1,5 @@
+DomainListing
+=============
+
+.. autoclass:: praw.models.DomainListing
+   :inherited-members:
diff --git a/docs/code_overview/other/moderatorrelationship.rst b/docs/code_overview/other/moderatorrelationship.rst
@@ -0,0 +1,5 @@
+ModeratorRelationship
+=======================
+
+.. autoclass:: praw.models.reddit.subreddit.ModeratorRelationship
+   :inherited-members:
diff --git a/docs/code_overview/other/submissionflair.rst b/docs/code_overview/other/submissionflair.rst
@@ -0,0 +1,5 @@
+SubmissionFlair
+===============
+
+.. autoclass:: praw.models.reddit.submission.SubmissionFlair
+   :inherited-members:
diff --git a/docs/code_overview/other/submissionmoderation.rst b/docs/code_overview/other/submissionmoderation.rst
@@ -0,0 +1,5 @@
+SubmissionModeration
+====================
+
+.. autoclass:: praw.models.reddit.submission.SubmissionModeration
+   :inherited-members:
diff --git a/docs/code_overview/other/subredditflair.rst b/docs/code_overview/other/subredditflair.rst
@@ -0,0 +1,5 @@
+SubredditFlair
+===============
+
+.. autoclass:: praw.models.reddit.subreddit.SubredditFlair
+   :inherited-members:
diff --git a/docs/code_overview/other/subredditflairtemplates.rst b/docs/code_overview/other/subredditflairtemplates.rst
@@ -0,0 +1,5 @@
+SubredditFlairTemplates
+=======================
+
+.. autoclass:: praw.models.reddit.subreddit.SubredditFlairTemplates
+   :inherited-members:
diff --git a/docs/code_overview/other/subredditmessage.rst b/docs/code_overview/other/subredditmessage.rst
@@ -0,0 +1,5 @@
+SubredditMessage
+================
+
+.. autoclass:: praw.models.SubredditMessage
+   :inherited-members:
diff --git a/docs/code_overview/other/subredditmoderation.rst b/docs/code_overview/other/subredditmoderation.rst
@@ -0,0 +1,5 @@
+SubredditModeration
+===================
+
+.. autoclass:: praw.models.reddit.subreddit.SubredditModeration
+   :inherited-members:
diff --git a/docs/code_overview/other/subredditrelationship.rst b/docs/code_overview/other/subredditrelationship.rst
@@ -0,0 +1,5 @@
+SubredditRelationship
+=======================
+
+.. autoclass:: praw.models.reddit.subreddit.SubredditRelationship
+   :inherited-members:
diff --git a/docs/code_overview/other/subredditstream.rst b/docs/code_overview/other/subredditstream.rst
@@ -0,0 +1,5 @@
+SubredditStream
+===============
+
+.. autoclass:: praw.models.reddit.subreddit.SubredditStream
+   :inherited-members:
diff --git a/docs/code_overview/other/subredditstylesheet.rst b/docs/code_overview/other/subredditstylesheet.rst
@@ -0,0 +1,5 @@
+SubredditStylesheet
+===================
+
+.. autoclass:: praw.models.reddit.subreddit.SubredditStylesheet
+   :inherited-members:
diff --git a/docs/code_overview/other/subredditwiki.rst b/docs/code_overview/other/subredditwiki.rst
@@ -0,0 +1,5 @@
+SubredditWiki
+=============
+
+.. autoclass:: praw.models.reddit.subreddit.SubredditWiki
+   :inherited-members:
diff --git a/docs/code_overview/other/wikipagemoderation.rst b/docs/code_overview/other/wikipagemoderation.rst
@@ -0,0 +1,5 @@
+WikiPageModeration
+==================
+
+.. autoclass:: praw.models.reddit.wikipage.WikiPageModeration
+   :inherited-members:
diff --git a/docs/code_overview/praw_models.rst b/docs/code_overview/praw_models.rst
@@ -0,0 +1,16 @@
+Working with PRAW's Models
+==========================
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Models
+
+   models/comment
+   models/livethread
+   models/message
+   models/more
+   models/multireddit
+   models/redditor
+   models/submission
+   models/subreddit
+   models/wikipage
diff --git a/docs/code_overview/reddit/front.rst b/docs/code_overview/reddit/front.rst
@@ -0,0 +1,5 @@
+reddit.front
+============
+
+.. autoclass:: praw.models.Front
+   :inherited-members:
diff --git a/docs/code_overview/reddit/inbox.rst b/docs/code_overview/reddit/inbox.rst
@@ -0,0 +1,5 @@
+reddit.inbox
+============
+
+.. autoclass:: praw.models.Inbox
+   :inherited-members:
diff --git a/docs/code_overview/reddit/live.rst b/docs/code_overview/reddit/live.rst
@@ -0,0 +1,5 @@
+reddit.live
+===========
+
+.. autoclass:: praw.models.LiveHelper
+   :inherited-members:
diff --git a/docs/code_overview/reddit/multireddit.rst b/docs/code_overview/reddit/multireddit.rst
@@ -0,0 +1,5 @@
+reddit.multireddit
+==================
+
+.. autoclass:: praw.models.MultiredditHelper
+   :inherited-members:
diff --git a/docs/code_overview/reddit/subreddit.rst b/docs/code_overview/reddit/subreddit.rst
@@ -0,0 +1,5 @@
+reddit.subreddit
+================
+
+.. autoclass:: praw.models.SubredditHelper
+   :inherited-members:
diff --git a/docs/code_overview/reddit/subreddits.rst b/docs/code_overview/reddit/subreddits.rst
@@ -0,0 +1,5 @@
+reddit.subreddits
+=================
+
+.. autoclass:: praw.models.Subreddits
+   :inherited-members:
diff --git a/docs/code_overview/reddit/user.rst b/docs/code_overview/reddit/user.rst
@@ -0,0 +1,5 @@
+reddit.user
+===========
+
+.. autoclass:: praw.models.User
+   :inherited-members:
diff --git a/docs/code_overview/reddit_instance.rst b/docs/code_overview/reddit_instance.rst
@@ -0,0 +1,17 @@
+The Reddit Instance
+===================
+
+.. autoclass:: praw.Reddit
+   :inherited-members:
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Helper Classes
+
+   reddit/front
+   reddit/inbox
+   reddit/live
+   reddit/multireddit
+   reddit/subreddit
+   reddit/subreddits
+   reddit/user
diff --git a/docs/conf.py b/docs/conf.py
@@ -10,7 +10,7 @@
 html_static_path = ['_static']
 html_theme = 'sphinx_rtd_theme'
 html_theme_options = {
-    'collapse_navigation': False
+    'collapse_navigation': True
 }
 html_use_smartypants = True
 htmlhelp_basename = 'PRAW'

diff --git a/docs/getting_started/authentication.rst b/docs/getting_started/authentication.rst
@@ -0,0 +1,2 @@
+Authenticating via OAuth
+========================
diff --git a/docs/getting_started/configuration.rst b/docs/getting_started/configuration.rst
@@ -0,0 +1,4 @@
+.. _configuration:
+
+Configuring PRAW
+================
diff --git a/docs/getting_started/installation.rst b/docs/getting_started/installation.rst
@@ -0,0 +1,2 @@
+Installing PRAW
+===============