These were referred to by other parts of the documentation, and they
provide core parts of our functionality, so we should have explicit
documentation for them.
It doesn't look like we need:
- `sphinx.ext.githubpages`
- `sphinx.ext.todo`
- `sphinx.ext.mathjax`
So I removed these and then sorted the list of extensions.
This commit mostly focuses on f-strings, collections, comprehensions,
and subscripts/slices.
I added intersphinx support to the sphinx config so I could link to
`ast.literal_eval`.
I exported BaseSimpleComp, since I felt it had some documentation value.
Fixed Why LibCST printed example as it was out of date.
Unrolled README example into Why LibCST section to decouple since this page explicitly uses "fn(1, 2)" snippet and the readme is going to change.
Added justification and pros/cons to LibCST.
Added graphviz to render the non-default parts of LibCST tree (identical to how we render non-default parts of the AST).
I haven't gone through every expression and cleaned it up yet, but I
have completed the `Names and Object Attributes`, `Operations and
Comparisons`, `Control Flow`, and `Lambda and Function Calls` sections,
as well as part of the `Literal Values` section.
This adds a __repr__ to various types in the parser config, so that the
generated documentation for functions using these types renders easier
to read.
Groups the expression nodes into much smaller subcategories for improved
readablility.
Some nodes defined in the expression module were grouped with statements
because they made more sense there (from a documentation perspective).
This also adds a local table of contents to the top of the nodes page
which better reveals all of the subcategories.
It also exports and categorizes
`BaseAssignTargetExpression`/`BaseDelTargetExpression`. These nodes were
referenced in type annotations of other nodes, so they need to be
exported if only for documentation reasons.
Removes the leading dot in node references (due to a misunderstanding I had), and uses tilde-based prefixes for restructured text references for consistency with the rest of the docs.
I added this originally because it's part of Python's grammar, but since
we merged parenthesis and friends into expressions instead of forming
separate nodes, BaseAtom doesn't have much use.
This fixes also a few bugs:
- A decorator requires a `dotted_name`, so it can only take a `Name` or
an `Attribute` node, not any atom.
- A `Call` node's function can be any expression, not just a fixed list
of `BaseExpression` subclasses.
- Now that we're exporting everything from the top-level libcst package,
automodule makes a mess of things.
- While it does create more boilerplate, using autoclass/autofunction
instead of automodule gives us a lot more control over the order in
which nodes are presented, so we can group them by various categories.
This diff also exports BaseParenthesizableWhitespace, because nodes
refer to it by type, and so it's needed for documentation purposes.
Without this option, autodoc defaults to ordering all members of
modules and classes alphabetically.
While this is normally fine (and probably desirable), the ordering of
fields in dataclasses is significant, so we need to change this behavior
to preserve the original member ordering.
