Add autorule + heavy refactoring

Author: taminomara

CHANGELOG.md

@@ -2,9 +2,22 @@
 
 ## [unreleased]
 
-## [1.0.1-post2]
+## [1.1.0]
 
-- Fix links after move.
+- Added `syntax:autorule`.
+
+- Fixed bugs related to propagating options to nested objects.
+
+- Autodoc-related options can be used with the `diagram` directive,
+  they'll be picked up by nested `autorule`, `lexer-diagram`, and `parser-diagram`.
+
+- Clarified documentation around the `:import:` option. It only has effect
+  on grammar declarations, despite documentation mentioning that it can be used
+  on diagrams.
+
+- Fixed links after move.
+
+- Releases are no longer uploaded to test version of PyPi.
 
 ## [1.0.1-post1]
 
@@ -26,8 +39,8 @@
 
 - Initial release.
 
-[unreleased]: https://github.com/sphinx-contrib/syntax/compare/v1.0.1-post2...HEAD
-[1.0.1-post2]: https://github.com/sphinx-contrib/syntax/compare/v1.0.1-post1...v1.0.1-post1
+[unreleased]: https://github.com/sphinx-contrib/syntax/compare/v1.1.0...HEAD
+[1.1.0]: https://github.com/sphinx-contrib/syntax/compare/v1.0.1-post1...v1.0.1-post1
 [1.0.1-post1]: https://github.com/sphinx-contrib/syntax/compare/v1.0.1...v1.0.1-post1
 [1.0.1]: https://github.com/sphinx-contrib/syntax/compare/v1.0.0-post1...v1.0.1
 [1.0.0-post1]: https://github.com/sphinx-contrib/syntax/compare/v1.0.0...v1.0.0-post1

docs/source/autodoc.rst

@@ -41,8 +41,8 @@ Autodoc directive
     .. rst:directive:option:: mark-root-rule
                               no-mark-root-rule
 
-        If enabled, automatic diagram for the :rst:dir:`root-rule <syntax:autogrammar:root-rule>`
-        will use complex line endings, while other diagrams will use simple ones
+        If enabled, diagrams in the :rst:dir:`root-rule <syntax:autogrammar:root-rule>`
+        will use complex line endings, while diagrams in other rules will use simple ones
         (see :rst:dir:`end-class <syntax:diagram:end-class>`).
 
     .. rst:directive:option:: diagrams
@@ -136,6 +136,17 @@ Autodoc directive
                 :literal-rendering: contents-unquoted
                 :svg-padding: 10 1 1 1
 
+.. rst:directive:: .. syntax:autorule:: <path> <name>
+
+    Documents a single rule from the given grammar.
+
+    This directive should be used inside :rst:dir:`syntax:grammar`; name of the
+    current grammar should match name of the autorule's grammar.
+
+    This directive supports all options from :rst:dir:`syntax:rule`,
+    including overrides for :rst:dir:`syntax:lexer-diagram`,
+    :rst:dir:`syntax:parser-diagram`, and automatically generated diagrams.
+
 
 .. _comments-syntax:
 

docs/source/directives.rst

@@ -23,153 +23,229 @@ Objects
 
     Grammars can't be nested, they also can't appear inside production rules.
 
-.. rst:directive:: .. syntax:rule:: name
+    **Options:**
 
-    Directive for documenting production rules:
+    .. rst:directive:option:: no-index
+                              no-index-entry
+                              no-contents-entry
+                              no-typesetting
 
-    .. code-block:: rst
+        The `standard Sphinx options`__ available to all object descriptions.
 
-        .. syntax:rule:: MyRule
+        __ https://www.sphinx-doc.org/en/master/usage/domains/index.html#basic-markup
 
-            Description.
+    .. rst:directive:option:: name: <text>
 
-    .. dropdown:: Example output
+        Sets a human readable name for a rule or a grammar.
 
-        .. syntax:rule:: MyRule
-            :no-index:
+        The primary name is used to refer to an object in documentation; it's used
+        in HTML paths, anchors, and serves as a unique object identifier.
 
-            Description.
+        The human readable name is used to display object to a user; it's used
+        when rendering documentation and cross-references.
 
-    Rules can't be nested.
+        **Example:**
 
+        .. code-block:: rst
 
-Parameters
-----------
+            .. syntax:grammar:: PrimaryName
+                :name: Human readable name
 
-All of the above directives accept the standard parameters:
+                Notice that anchor for this grammar uses its primary name.
 
-.. rst:directive:option:: no-index
-                          no-index-entry
-                          no-contents-entry
-                          no-typesetting
+            When referring to an object, we use primary name: :syntax:g:`PrimaryName`.
+            When this cross-reference is rendered, though,
+            it will use a human readable name.
 
-    The `standard Sphinx options`__ available to all object descriptions.
+        .. dropdown:: Example output
 
-    __ https://www.sphinx-doc.org/en/master/usage/domains/index.html#basic-markup
+            .. syntax:grammar:: PrimaryName
+                :name: Human readable name
+                :no-index-entry:
+                :no-contents-entry:
 
-.. rst:directive:option:: name: <text>
+                Notice that anchor for this grammar uses its primary name.
 
-    Sets a human readable name for a rule or a grammar.
+            When referring to an object, we use primary name: :syntax:g:`PrimaryName`.
+            When this cross-reference is rendered, though,
+            it will use a human readable name.
 
-    The primary name is used to refer to an object in documentation; it's used
-    in HTML paths, anchors, and serves as a unique object identifier.
+    .. rst:directive:option:: imports: <list of diagram names>
 
-    The human readable name is used to display object to a user; it's used
-    when rendering documentation and cross-references.
+        If your parser generators allows importing grammars, you can use ``imports``
+        option to specify which diagrams are imported from the documented one.
 
-    **Example:**
+        This will affect object resolution for cross-references and diagrams.
 
-    .. code-block:: rst
+        **Example:**
 
-        .. syntax:grammar:: PrimaryName
-            :name: Human readable name
+        .. code-block:: rst
 
-            Notice that anchor for this grammar uses its primary name.
+            .. syntax:grammar:: BaseGrammar
 
-        When referring to an object, we use primary name: :syntax:g:`PrimaryName`.
-        When this cross-reference is rendered, though,
-        it will use a human readable name.
+                .. syntax:rule:: BaseRule
 
-    .. dropdown:: Example output
+            .. syntax:grammar:: DownstreamGrammar
+                :imports: BaseGrammar
 
-        .. syntax:grammar:: PrimaryName
-            :name: Human readable name
+                This grammar imports :syntax:g:`BaseGrammar`, so it can reference
+                its rules without prefixing them with grammar name:
+                :syntax:r:`BaseRule`.
 
-            Notice that anchor for this grammar uses its primary name.
+                This also works in diagrams:
 
-        When referring to an object, we use primary name: :syntax:g:`PrimaryName`.
-        When this cross-reference is rendered, though,
-        it will use a human readable name.
+                .. syntax:diagram:: BaseRule
 
-.. rst:directive:option:: imports: <list of diagram names>
+        .. dropdown:: Example output
 
-    If your parser generators allows importing grammars, you can use ``imports``
-    option to specify which diagrams are imported from the documented one.
+            .. syntax:grammar:: BaseGrammar
+                :no-index-entry:
+                :no-contents-entry:
 
-    This will affect object resolution for cross-references and diagrams.
+                .. syntax:rule:: BaseRule
+                    :no-index-entry:
+                    :no-contents-entry:
 
-    **Example:**
+            .. syntax:grammar:: DownstreamGrammar
+                :imports: BaseGrammar
+                :no-index-entry:
+                :no-contents-entry:
 
-    .. code-block:: rst
+                This grammar imports :syntax:g:`BaseGrammar`, so it can reference
+                its rules without prefixing them with grammar name:
+                :syntax:r:`BaseRule`.
 
-        .. syntax:grammar:: BaseGrammar
+                This also works in diagrams:
 
-            .. syntax:rule:: BaseRule
+                .. syntax:diagram:: BaseRule
 
-        .. syntax:grammar:: DownstreamGrammar
-            :imports: BaseGrammar
+    .. rst:directive:option:: root-rule: <rule> | <grammar>.<rule> | <path> <rule>
 
-            This grammar imports :syntax:g:`BaseGrammar`, so it can reference
-            its rules without prefixing them with grammar name:
-            :syntax:r:`BaseRule`.
+        Specifies root rule of the diagram.
 
-            This also works in diagrams:
+        Setting a root rule has two effects:
 
-            .. syntax:diagram:: BaseRule
+        1.  If :rst:dir:`mark-root-rule <syntax:grammar:mark-root-rule>` is enabled,
+            syntax diagrams for the root rule will use use complex line endings,
+            while syntax diagrams for all other rules will use simple ones.
 
-    .. dropdown:: Example output
+        2.  :rst:dir:`syntax:autogrammar` will not display rules that aren't reachable
+            from the root rule.
 
-        .. syntax:grammar:: BaseGrammar
+            See :rst:dir:`example in syntax:autogrammar <syntax:autogrammar:root-rule>`.
 
-            .. syntax:rule:: BaseRule
+        The value should be either name of a rule from the grammar that’s
+        being documented, a grammar name and a rule name separated by a dot,
+        or a grammar file and a rule name separated by a space.
 
-        .. syntax:grammar:: DownstreamGrammar
-            :imports: BaseGrammar
+    .. rst:directive:option:: mark-root-rule
+                              no-mark-root-rule
 
-            This grammar imports :syntax:g:`BaseGrammar`, so it can reference
-            its rules without prefixing them with grammar name:
-            :syntax:r:`BaseRule`.
+        If enabled, diagrams in the :rst:dir:`root-rule <syntax:autogrammar:root-rule>`
+        will use complex line endings, while diagrams in other rules will use simple ones
+        (see :rst:dir:`end-class <syntax:diagram:end-class>`).
 
-            This also works in diagrams:
+        With this option turned off, :rst:dir:`root-rule <syntax:grammar:root-rule>`
+        only affects how :rst:dir:`syntax:autogrammar` filters displayed rules.
 
-            .. syntax:diagram:: BaseRule
+    .. rst:directive:option:: diagrams
+                              no-diagrams
+                              cc-to-dash
+                              no-cc-to-dash
+                              bison-c-char-literals
+                              no-bison-c-char-literals
+                              literal-rendering
 
-.. rst:directive:option:: diagram-*
+        Same as corresponding options from :rst:dir:`syntax:autogrammar`.
 
-    You can add any option from :rst:dir:`syntax:diagram` to an object description
-    by prefixing it with ``diagram-``. This option will be used in all diagrams
-    that appear within object's description.
+        When used on :rst:dir:`syntax:grammar`, these options override defaults
+        for any nested :rst:dir:`syntax:autorule`, :rst:dir:`syntax:lexer-diagram`
+        or :rst:dir:`syntax:parser-diagram`.
 
-    **Example:**
+    .. rst:directive:option:: diagram-*
 
-    .. code-block:: rst
+        These options override defaults for any :rst:dir:`syntax:diagram`
+        used within this grammar.
 
-        .. syntax:grammar:: MyGrammar
-            :diagram-end-class: simple
+        **Example:**
+
+        .. code-block:: rst
+
+            .. syntax:grammar:: MyGrammar
+                :diagram-end-class: simple
+
+                All diagrams in this grammar will use simple end class:
+
+                .. syntax:diagram:: Simple end class
 
-            All diagrams in this grammar will use simple end class:
+                Unless they override it manually:
 
-            .. syntax:diagram:: Simple end class
+                .. syntax:diagram:: Complex end class
+                    :end-class: complex
+
+        .. dropdown:: Example output
+
+            .. syntax:grammar:: MyGrammar
+                :no-index:
+                :diagram-end-class: simple
+
+                All diagrams in this grammar will use simple end class:
+
+                .. syntax:diagram:: Simple end class
+
+                Unless they override it manually:
+
+                .. syntax:diagram:: Complex end class
+                    :end-class: complex
+
+
+.. rst:directive:: .. syntax:rule:: name
+
+    Directive for documenting production rules:
+
+    .. code-block:: rst
 
-            Unless they override it manually:
+        .. syntax:rule:: MyRule
 
-            .. syntax:diagram:: Complex end class
-                :end-class: complex
+            Description.
 
     .. dropdown:: Example output
 
-        .. syntax:grammar:: MyGrammar
+        .. syntax:rule:: MyRule
             :no-index:
-            :diagram-end-class: simple
 
-            All diagrams in this grammar will use simple end class:
+            Description.
+
+    Rules can't be nested.
+
+    **Options:**
+
+    .. rst:directive:option:: no-index
+                              no-index-entry
+                              no-contents-entry
+                              no-typesetting
+
+        The `standard Sphinx options`__ available to all object descriptions.
+
+        __ https://www.sphinx-doc.org/en/master/usage/domains/index.html#basic-markup
 
-            .. syntax:diagram:: Simple end class
+    .. rst:directive:option:: name: <text>
 
-            Unless they override it manually:
+        Sets a human readable name for a rule or a grammar.
 
-            .. syntax:diagram:: Complex end class
-                :end-class: complex
+        See :rst:dir:`syntax:grammar:name` for more info.
+
+    .. rst:directive:option:: diagram-*
+                              diagrams
+                              no-diagrams
+                              cc-to-dash
+                              no-cc-to-dash
+                              bison-c-char-literals
+                              no-bison-c-char-literals
+                              literal-rendering
+
+        Same as corresponding options from :rst:dir:`syntax:grammar`
+        and :rst:dir:`syntax:autogrammar`.
 
 
 Diagrams
@@ -317,7 +393,7 @@ but allows less customization.
 
         .. syntax:lexer-diagram:: ('+' | '-')? ([1-9][0-9]* | '0')
 
-    **Options**
+    **Options:**
 
     All options from the :rst:dir:`syntax:diagram` directive ara available,
     as well as :rst:dir:`syntax:autogrammar:cc-to-dash`
@@ -345,7 +421,7 @@ but allows less customization.
                 '*' | expression (AS row_name)? (',' expression (AS row_name)?)*
             )
 
-    **Options**
+    **Options:**
 
     All options from the :rst:dir:`syntax:diagram` directive ara available,
     as well as :rst:dir:`syntax:autogrammar:cc-to-dash`