WIP: point Sphinx directly at real modules

docs/pyparsing.rst

@@ -2,6 +2,38 @@ pyparsing module
 ================
 
 .. automodule:: pyparsing
+
+.. automodule:: pyparsing.core
+    :members:
+    :special-members:
+    :show-inheritance:
+
+.. automodule:: pyparsing.results
+    :members:
+    :special-members:
+    :show-inheritance:
+
+.. automodule:: pyparsing.actions
+    :members:
+    :special-members:
+    :show-inheritance:
+
+.. automodule:: pyparsing.helpers
+    :members:
+    :special-members:
+    :show-inheritance:
+
+.. automodule:: pyparsing.common
+    :members:
+    :special-members:
+    :show-inheritance:
+
+.. automodule:: pyparsing.unicode
+    :members:
+    :special-members:
+    :show-inheritance:
+
+.. automodule:: pyparsing.exceptions
     :members:
     :special-members:
     :show-inheritance:

pyparsing/__init__.py

@@ -34,10 +34,10 @@
 grammar directly in Python.
 
 Here is a program to parse "Hello, World!" (or any greeting of the form
-``"<salutation>, <addressee>!"``), built up using :class:`Word`,
-:class:`Literal`, and :class:`And` elements
-(the :meth:`'+'<ParserElement.__add__>` operators create :class:`And` expressions,
-and the strings are auto-converted to :class:`Literal` expressions)::
+``"<salutation>, <addressee>!"``), built up using :class:`.Word`,
+:class:`.Literal`, and :class:`.And` elements
+(the :meth:`'+'<ParserElement.__add__>` operators create :class:`.And` expressions,
+and the strings are auto-converted to :class:`.Literal` expressions)::
 
     from pyparsing import Word, alphas
 
@@ -52,12 +52,13 @@
     Hello, World! -> ['Hello', ',', 'World', '!']
 
 The Python representation of the grammar is quite readable, owing to the
-self-explanatory class names, and the use of :class:`'+'<And>`,
-:class:`'|'<MatchFirst>`, :class:`'^'<Or>` and :class:`'&'<Each>` operators.
+self-explanatory class names, and the use of :class:`'+'<pyparsing.core.And>`,
+:class:`'|'<pyparsing.core.MatchFirst>`, :class:`'^'<pyparsing.core.Or>` and
+:class:`'&'<pyparsing.core.Each>` operators.
 
-The :class:`ParseResults` object returned from
-:class:`ParserElement.parse_string` can be
-accessed as a nested list, a dictionary, or an object with named
+The :class:`.ParseResults` object returned from
+:class:`ParserElement.parse_string<pyparsing.core.ParserElement.parse_string>`
+can be accessed as a nested list, a dictionary, or an object with named
 attributes.
 
 The pyparsing module handles some of the problems that are typically
@@ -71,26 +72,26 @@
 
 Getting Started -
 -----------------
-Visit the classes :class:`ParserElement` and :class:`ParseResults` to
+Visit the classes :class:`.ParserElement` and :class:`.ParseResults` to
 see the base classes that most other pyparsing
 classes inherit from. Use the docstrings for examples of how to:
 
- - construct literal match expressions from :class:`Literal` and
-   :class:`CaselessLiteral` classes
- - construct character word-group expressions using the :class:`Word`
+ - construct literal match expressions from :class:`.Literal` and
+   :class:`.CaselessLiteral` classes
+ - construct character word-group expressions using the :class:`.Word`
    class
- - see how to create repetitive expressions using :class:`ZeroOrMore`
-   and :class:`OneOrMore` classes
- - use :class:`'+'<And>`, :class:`'|'<MatchFirst>`, :class:`'^'<Or>`,
-   and :class:`'&'<Each>` operators to combine simple expressions into
+ - see how to create repetitive expressions using :class:`.ZeroOrMore`
+   and :class:`.OneOrMore` classes
+ - use :class:`'+'<pyparsing.core.And>`, :class:`'|'<pyparsing.core.MatchFirst>`, :class:`'^'<pyparsing.core.Or>`,
+   and :class:`'&'<pyparsing.core.Each>` operators to combine simple expressions into
    more complex ones
  - associate names with your parsed results using
-   :class:`ParserElement.set_results_name`
- - access the parsed data, which is returned as a :class:`ParseResults`
+   :class:`ParserElement.set_results_name<pyparsing.core.ParserElement.set_results_name>`
+ - access the parsed data, which is returned as a :class:`.ParseResults`
    object
- - find some helpful expression short-cuts like :class:`delimited_list`
-   and :class:`one_of`
- - find more useful common expressions in the :class:`pyparsing_common`
+ - find some helpful expression short-cuts like :class:`~pyparsing.helpers.delimited_list`
+   and :class:`~pyparsing.helpers.one_of`
+ - find more useful common expressions in the :class:`.pyparsing_common`
    namespace class
 """
 from typing import NamedTuple

pyparsing/actions.py

@@ -1,4 +1,8 @@
 # actions.py
+"""
+pyparsing.actions
+-----------------
+"""
 
 from .exceptions import ParseException
 from .util import col
@@ -199,7 +203,12 @@ def with_class(classname, namespace=""):
 
 # pre-PEP8 compatibility symbols
 replaceWith = replace_with
+"""Deprecated - use :class:`replace_with`"""
 removeQuotes = remove_quotes
+"""Deprecated - use :class:`remove_quotes`"""
 withAttribute = with_attribute
+"""Deprecated - use :class:`with_attribute`"""
 withClass = with_class
+"""Deprecated - use :class:`with_class`"""
 matchOnlyAtCol = match_only_at_col
+"""Deprecated - use :class:`match_only_at_col`"""

pyparsing/common.py

@@ -1,4 +1,9 @@
 # common.py
+"""
+pyparsing.common
+----------------
+"""
+
 from .core import *
 from .helpers import delimited_list, any_open_tag, any_close_tag
 from datetime import datetime
@@ -407,6 +412,7 @@ def strip_html_tags(s: str, l: int, tokens: ParseResults):
         r"(#(?P<fragment>\S*))?" +
         r"$"
     ).set_name("url")
+    """Predefined expression for parsing a URL."""
     # fmt: on
 
     # pre-PEP8 compatibility names