Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add support for Python raw docstrings #356

Merged
merged 1 commit into from Nov 22, 2022
Merged

Add support for Python raw docstrings #356

merged 1 commit into from Nov 22, 2022

Conversation

wbadart
Copy link
Contributor

@wbadart wbadart commented Nov 22, 2022

Sometimes, in Python, a docstring will be a raw (r"...") string, as opposed to a regular ("...") string (I've seen this when a docstring needs to escape things in funny ways for sphinx). This commit adds two entries to the Python.quote section of languages.json (and the corresponding update to constants.go) for recognizing these raw docstrings as docs rather than code.

For example, without this commit, for the file

r"""Welcome to foo.py! Sometimes I escape :class:`thing`\s funny when
Sphinx is involved.
"""

def hello():
    pass

scc reports

───────────────────────────────────────────────────────────────────────────────
Language                 Files     Lines   Blanks  Comments     Code Complexity
───────────────────────────────────────────────────────────────────────────────
Python                       1         6        0         0        6          0
───────────────────────────────────────────────────────────────────────────────
Total                        1         6        0         0        6          0
───────────────────────────────────────────────────────────────────────────────
Estimated Cost to Develop (organic) $125
Estimated Schedule Effort (organic) 0.45 months
Estimated People Required (organic) 0.02
───────────────────────────────────────────────────────────────────────────────
Processed 117 bytes, 0.000 megabytes (SI)
───────────────────────────────────────────────────────────────────────────────

But with this commit, reports

───────────────────────────────────────────────────────────────────────────────
Language                 Files     Lines   Blanks  Comments     Code Complexity
───────────────────────────────────────────────────────────────────────────────
Python                       1         6        1         3        2          0
───────────────────────────────────────────────────────────────────────────────
Total                        1         6        1         3        2          0
───────────────────────────────────────────────────────────────────────────────
Estimated Cost to Develop (organic) $39
Estimated Schedule Effort (organic) 0.29 months
Estimated People Required (organic) 0.01
───────────────────────────────────────────────────────────────────────────────
Processed 117 bytes, 0.000 megabytes (SI)
───────────────────────────────────────────────────────────────────────────────

Thanks for your consideration!

(I submit this contribution under the terms of LICENSE and UNLICENSE.)

Sometimes, in Python, a docstring will be a raw (`r"..."`) string, as
opposed to a regular (`"..."`) string (I've seen this when a docstring
needs to escape things in funny ways for sphinx). This commit adds two
entries to the `Python.quote` section of `languages.json` (and the
corresponding update to `constants.go`) for recognizing these raw
docstrings as docs rather than code.

For example, without this commit, for the file

```python
r"""Welcome to foo.py! Sometimes I escape :class:`thing`\s funny when
Sphinx is involved.
"""

def hello():
    pass
```

`scc` reports

```
───────────────────────────────────────────────────────────────────────────────
Language                 Files     Lines   Blanks  Comments     Code Complexity
───────────────────────────────────────────────────────────────────────────────
Python                       1         6        0         0        6          0
───────────────────────────────────────────────────────────────────────────────
Total                        1         6        0         0        6          0
───────────────────────────────────────────────────────────────────────────────
Estimated Cost to Develop (organic) $125
Estimated Schedule Effort (organic) 0.45 months
Estimated People Required (organic) 0.02
───────────────────────────────────────────────────────────────────────────────
Processed 117 bytes, 0.000 megabytes (SI)
───────────────────────────────────────────────────────────────────────────────
```

But with this commit, reports

```
───────────────────────────────────────────────────────────────────────────────
Language                 Files     Lines   Blanks  Comments     Code Complexity
───────────────────────────────────────────────────────────────────────────────
Python                       1         6        1         3        2          0
───────────────────────────────────────────────────────────────────────────────
Total                        1         6        1         3        2          0
───────────────────────────────────────────────────────────────────────────────
Estimated Cost to Develop (organic) $39
Estimated Schedule Effort (organic) 0.29 months
Estimated People Required (organic) 0.01
───────────────────────────────────────────────────────────────────────────────
Processed 117 bytes, 0.000 megabytes (SI)
───────────────────────────────────────────────────────────────────────────────
```

Thanks for your consideration!
@boyter
Copy link
Owner

boyter commented Nov 22, 2022

Oh very nice! Not sure how I managed to miss that! Thanks for the fix.

@boyter boyter merged commit ab483bb into boyter:master Nov 22, 2022
@boyter boyter added the bug Something isn't working label Nov 22, 2022
@wbadart
Copy link
Contributor Author

wbadart commented Nov 22, 2022

@boyter thanks for the quick response. What's your release process like? (Wondering when I should replace my local build with a brew upgrade.)

@boyter
Copy link
Owner

boyter commented Nov 23, 2022

@wbadart Mostly its when I hit some level of new functionality... I don't actually maintain any of the repo manager distributions. I did consider it, but its far more work than I am willing to put in. If someone wants to own the official releases of them all and put them into this repo however I would be more than willing to help out.

For the moment though, unstable master is not a bad idea. The test suite ensures regressions are very rare.

@wbadart
Copy link
Contributor Author

wbadart commented Nov 28, 2022

Gotcha, sounds good!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
bug Something isn't working
Projects
None yet
Development

Successfully merging this pull request may close these issues.

None yet

2 participants