RST: Detect :: signifying default language code-block.
#195
Comments
|
Ah, I've missed the point there: the change was added by hand in order to get blacken-docs to register the code block. Ref
We have to add the explicit Could the |
carltongibson
changed the title
:: signifying default language code-block.
A reason to support this is quite simply to have a way for a large documentation project like Django to introduce blacken-docs without also having a huge changeset related to refactoring But I'm not sure, @carltongibson - given the already quite huge changeset - if it matters much. It's just huge changeset vs. also huge changeset 😄 |
|
It's not just the change set. It's the more verbose code style throughout the project, forever more. 😳 |
|
Working on several Sphinx projects made me unable to remember what language the default |
|
That's OK. Disagreement on such is within the bounds of reason 😜 |
|
haha, indeed, I couldn't imagine a more classic way for developers to have different experiences than this ❤️ It's why there always exists |
|
#21 for previous discussion |
|
Thanks for the link back @asottile
|
|
Is this approach of interest @carltongibson - or too quirky yirky dirky? 😵💫 |
|
It's not just up to me 😄 Personally, I do want to keep the I still need to investigate all the changes but, I'm more concerned by the required Oh, it always has to be valid code changes. The trouble with skips is we no longer have an auto-formatter. What we need is a black-ish that will hand wave over the invalid bits. (Don't think that's on the table) You've been looking at this for while. I only just came to it. I also need to confer with Mariusz. (This seems more a discussion for the Django PR than here... 😬) |
|
I’m not in favour of this because I’ve always preferred using explicit |
It could, but if you're using Sphinx it isn't, it's Python. Projects created by
Sure. 👍 Hence it should clearly need a flag, like |
This commit makes use of the refactoring done in prior commits to slot
in reStructuredText support. Essentially, we add a new type of code
example and look for *both* literal blocks and code block directives.
Literal blocks are treated as Python by default because it seems to be a
common practice[1].
That is, literal blocks like this:
```
def example():
"""
Here's an example::
foo( 1 )
All done.
"""
pass
```
Will get reformatted. And code blocks (via reStructuredText directives)
will also get reformatted:
```
def example():
"""
Here's an example:
.. code-block:: python
foo( 1 )
All done.
"""
pass
```
When looking for a code block, it is possible for it to become invalid.
In which case, we back out of looking for a code example and print the
lines out as they are. As with doctest formatting, if reformatting the
code would result in invalid Python or if the code collected from the
block is invalid, then formatting is also skipped.
A number of tests have been added to check both the formatting and
resetting behavior. Mixed indentation is also tested a fair bit, since
one of my initial attempts at dealing with mixed indentation ended up
not working.
Closes #8859
[1]: adamchainz/blacken-docs#195
This commit makes use of the refactoring done in prior commits to slot
in reStructuredText support. Essentially, we add a new type of code
example and look for *both* literal blocks and code block directives.
Literal blocks are treated as Python by default because it seems to be a
common practice[1].
That is, literal blocks like this:
```
def example():
"""
Here's an example::
foo( 1 )
All done.
"""
pass
```
Will get reformatted. And code blocks (via reStructuredText directives)
will also get reformatted:
```
def example():
"""
Here's an example:
.. code-block:: python
foo( 1 )
All done.
"""
pass
```
When looking for a code block, it is possible for it to become invalid.
In which case, we back out of looking for a code example and print the
lines out as they are. As with doctest formatting, if reformatting the
code would result in invalid Python or if the code collected from the
block is invalid, then formatting is also skipped.
A number of tests have been added to check both the formatting and
resetting behavior. Mixed indentation is also tested a fair bit, since
one of my initial attempts at dealing with mixed indentation ended up
not working.
Closes #8859
[1]: adamchainz/blacken-docs#195
This commit makes use of the refactoring done in prior commits to slot
in reStructuredText support. Essentially, we add a new type of code
example and look for *both* literal blocks and code block directives.
Literal blocks are treated as Python by default because it seems to be a
common practice[1].
That is, literal blocks like this:
```
def example():
"""
Here's an example::
foo( 1 )
All done.
"""
pass
```
Will get reformatted. And code blocks (via reStructuredText directives)
will also get reformatted:
```
def example():
"""
Here's an example:
.. code-block:: python
foo( 1 )
All done.
"""
pass
```
When looking for a code block, it is possible for it to become invalid.
In which case, we back out of looking for a code example and print the
lines out as they are. As with doctest formatting, if reformatting the
code would result in invalid Python or if the code collected from the
block is invalid, then formatting is also skipped.
A number of tests have been added to check both the formatting and
resetting behavior. Mixed indentation is also tested a fair bit, since
one of my initial attempts at dealing with mixed indentation ended up
not working.
Closes #8859
[1]: adamchainz/blacken-docs#195
This commit makes use of the refactoring done in prior commits to slot
in reStructuredText support. Essentially, we add a new type of code
example and look for *both* literal blocks and code block directives.
Literal blocks are treated as Python by default because it seems to be a
common practice[1].
That is, literal blocks like this:
```
def example():
"""
Here's an example::
foo( 1 )
All done.
"""
pass
```
Will get reformatted. And code blocks (via reStructuredText directives)
will also get reformatted:
```
def example():
"""
Here's an example:
.. code-block:: python
foo( 1 )
All done.
"""
pass
```
When looking for a code block, it is possible for it to become invalid.
In which case, we back out of looking for a code example and print the
lines out as they are. As with doctest formatting, if reformatting the
code would result in invalid Python or if the code collected from the
block is invalid, then formatting is also skipped.
A number of tests have been added to check both the formatting and
resetting behavior. Mixed indentation is also tested a fair bit, since
one of my initial attempts at dealing with mixed indentation ended up
not working.
Closes #8859
[1]: adamchainz/blacken-docs#195
This commit makes use of the refactoring done in prior commits to slot
in reStructuredText support. Essentially, we add a new type of code
example and look for *both* literal blocks and code block directives.
Literal blocks are treated as Python by default because it seems to be a
common practice[1].
That is, literal blocks like this:
```
def example():
"""
Here's an example::
foo( 1 )
All done.
"""
pass
```
Will get reformatted. And code blocks (via reStructuredText directives)
will also get reformatted:
```
def example():
"""
Here's an example:
.. code-block:: python
foo( 1 )
All done.
"""
pass
```
When looking for a code block, it is possible for it to become invalid.
In which case, we back out of looking for a code example and print the
lines out as they are. As with doctest formatting, if reformatting the
code would result in invalid Python or if the code collected from the
block is invalid, then formatting is also skipped.
A number of tests have been added to check both the formatting and
resetting behavior. Mixed indentation is also tested a fair bit, since
one of my initial attempts at dealing with mixed indentation ended up
not working.
Closes #8859
[1]: adamchainz/blacken-docs#195
(This is not possible to actually use until #8854 is merged.) ruff_python_formatter: add reStructuredText docstring formatting support This commit makes use of the refactoring done in prior commits to slot in reStructuredText support. Essentially, we add a new type of code example and look for *both* literal blocks and code block directives. Literal blocks are treated as Python by default because it seems to be a [common practice](adamchainz/blacken-docs#195). That is, literal blocks like this: ``` def example(): """ Here's an example:: foo( 1 ) All done. """ pass ``` Will get reformatted. And code blocks (via reStructuredText directives) will also get reformatted: ``` def example(): """ Here's an example: .. code-block:: python foo( 1 ) All done. """ pass ``` When looking for a code block, it is possible for it to become invalid. In which case, we back out of looking for a code example and print the lines out as they are. As with doctest formatting, if reformatting the code would result in invalid Python or if the code collected from the block is invalid, then formatting is also skipped. A number of tests have been added to check both the formatting and resetting behavior. Mixed indentation is also tested a fair bit, since one of my initial attempts at dealing with mixed indentation ended up not working. I recommend working through this PR commit-by-commit. There is in particular a somewhat gnarly refactoring before reST support is added. Closes #8859
blacken-docswill do this:But it's an old-as-time RST convention that the
::means the following code block is the default language (i.e. Python)Not respecting that is quite a lot of noise. Is there a way to control it? Could there be?
Thanks!
Refs django/django#16261
The text was updated successfully, but these errors were encountered: