Comments (8)
I think going with whatever is most consistent with the PEP makes sense here. I'll align my documentation to avail of this. Thanks for your help!
from cyclopts.
Thanks for using Cyclopts!
The space between the Usage-string and the description is intentional. Currently there is no way of removing this newline, but if you're curious, it's injected right here.
The newlines in the long_description
component of your docstring are a little less expected. This seems expected, however, according to the docstring_parser README. I would imagine an rst-like parsing would be ideal, and it seems like rich-rst would be the ticket, but I'm unsure about adding it as a dependency.
from cyclopts.
ok, revisiting this, I now understand what you meant, you meant this space:
Do something. this is a multi-line
comment wrapping over. words words words
That is indeed unintentional, let me dig in.
from cyclopts.
So diving in, the "problem" is kind of in parse_docstring.
In docstring_parser, they call inspect.cleandoc
. The example input is (without the leading/trailing single-quote):
'\n Do something. this is a multi-line\n comment wrapping over. words words words\n more words on more lines\n\n\n Args:\n name: something\n '
and the output of the inspect.cleandoc
call is:
'Do something. this is a multi-line\ncomment wrapping over. words words words\nmore words on more lines\n\n\nArgs:\n name: something'
The documentation says to refer to PEP-0257. Here are some important relevent quotes:
The summary line may be used by automatic indexing tools; it is important that it fits on one line and is separated from the rest of the docstring by a blank line. The summary line may be on the same line as the opening quotes or on the next line.
The issue here, is your docstring doesn't have a "summary" (aka short_description) line, and so it interprets your first non-blank line as such. I think this is a bit erroneous behavior, as the line Do something. this is a multi-line
doesn't have the mentioned blank-line.
So, if you format your docstring with the short_description, things will be formatted more as expected:
"""My function summary.
A multiline long description down here.
"""
My takeaway thoughts:
- It would be nice if the docstring body was rst-interpretted to make a prettier output.
- It would be nice if no summary-string is provided (delimited by the first
\n\n
), that the rest is interpreted aslong_description
.
from cyclopts.
a workaround: I could do something like the following:
docstring = "" # Imagine this is your docstring
parsed = docstring_parse(raw_doc_string) # call their docstring_parse
# Manual hacks
cleaned_docstring = inspect.doclean(docstring)
try:
short_description = cleaned_docstring.split("\n\n")[0]
except IndexError:
short_description = ""
if parsed.short_description != short_description:
# Reconstruct the proper docstring
parsed.long_description = parsed.short_description + "\n" + parsed.long_description
# Get rid of the ill-parsed short_description
parsed.short_description = None
# the rest of cyclopts help-page logic
Thoughts on something like this?
from cyclopts.
I merged in some code into v2.1.1 that implements the spirit of the above. I still think functions should generally have a short description (they're used in the help-page for the command panel), but I think the current splitting was erroneous.
As for rst/md parsing, we can continue discussion in #81.
from cyclopts.
Wow, I appreciate the expeditious response and solution! Your solution here sounds great. One thing to note, but it looks like the short description gets parsed into the top level help command as well. In the case of the above:
$ my_app
╭─ Commands────────────────────────────────────────╮
│ foo Do something. this is a multi-line │
╰──────────────────────────────────────────────────╯
(
In the context of the proposed solution, clearing the short description looks like it might result in this being blank (unless I'm wrong). I'm not sure what the solution here would be. Options would seem to be:
- leave short description blank here (doesn't feel right)
- truncating the long description (e.g. after n characters
Do something. this is a multi-line comment wrapping over. words ...
. Not super clean but not the worst. - Put the full long description in here. If users find it too long, that's on them to shorten it up or break it into short + long.
- Go with to the original behavior of just taking the first line and probably just document what will happen and why you want a short + long description.
I think most of those other than option 1 would feel alright. Option 3 feels the most flexible to different documentation styles.
from cyclopts.
Current behavior (as of v2.1.1) will be your (1):
- leave short description blank here (doesn't feel right)
(2) is a potential solution, but I don't think I want to deviate this far. Standard docstring syntax is:
"""My short summary.
A longer detailed description.
This is a continuation of that description.
"""
IMHO the current extension implemented in #82 is more consistent with PEP-0257, which is why I was ok with it. In short, I think it should be blank if there isn't a proper short_description. I don't think it's unreasonable to expect the user to provide a short_description/summary (standard practice) at the top of their docstring if they want the short_description field to be populated in the help-page.
from cyclopts.
Related Issues (20)
- support for union of None like Optional HOT 3
- App() name parameter type hint adjustment HOT 2
- Docstring hyperlink HOT 11
- [Feature request]: Nested pydantic validation HOT 9
- [Discussion] First-class config overrides via pyproject.toml? HOT 1
- [Feature Request] Completion? HOT 6
- App() console parameter HOT 2
- integration with https://pypi.org/project/typed-settings/ HOT 2
- [BUG]: bad error report because of assetion error when there is UnusedCliTokensError HOT 2
- [BUG] Weird behavior of list of tuples HOT 7
- [BUG] list of tuple of single item is parsed but take only the first character of each token get parsed HOT 2
- Misleading error message when flag name has an underscore HOT 2
- the help format parsing is not consistent HOT 2
- Misc likely (rare) typing bugs HOT 1
- Use of the meta application results in a double help display HOT 5
- Automatic conversion from underscore to hyphen HOT 3
- Prompt for missing required parameters HOT 6
- Newlines should not be present in descriptions that span multiple lines HOT 5
- [Feature Request] Add auto_env_var_prefix HOT 9
- Importing cyclopts fails if there is a file called "tokenize.py" in the project which imports cyclopts HOT 1
Recommend Projects
-
React
A declarative, efficient, and flexible JavaScript library for building user interfaces.
-
Vue.js
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
-
Typescript
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
-
TensorFlow
An Open Source Machine Learning Framework for Everyone
-
Django
The Web framework for perfectionists with deadlines.
-
Laravel
A PHP framework for web artisans
-
D3
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
-
Recommend Topics
-
javascript
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
-
web
Some thing interesting about web. New door for the world.
-
server
A server is a program made to process requests and deliver data to clients.
-
Machine learning
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
-
Visualization
Some thing interesting about visualization, use data art
-
Game
Some thing interesting about game, make everyone happy.
Recommend Org
-
Facebook
We are working to build community through open source technology. NB: members must have two-factor auth.
-
Microsoft
Open source projects and samples from Microsoft.
-
Google
Google ❤️ Open Source for everyone.
-
Alibaba
Alibaba Open Source for everyone
-
D3
Data-Driven Documents codes.
-
Tencent
China tencent open source team.
from cyclopts.