Comments (5)
From [email protected] on June 27, 2012 18:02:21
I'm in three minds how to solve this one.
The first approach is to modify the parser so that this bulleted syntax is accepted silently. In essence, it would become a completely acceptable syntax form for Cartouche, albeit one that goes beyond the informally specified Google syntax.
The second approach is to modify the parser to accept the bullet syntax as above, but to issue an advisory warning.
The third option is to issue a warning and to skip processing of the whole docstring. The unprocessed docstring will be passed through to Sphinx.
As ever, error recovery in parsers is difficult and I don't think it's worthwhile to attempt processing with the remainder of the docstring.
from cartouche.
From [email protected] on June 27, 2012 19:18:00
Patch to implement option (1) above attached. Still not convinced this is the right approach.
from cartouche.
From austin.bingham on June 28, 2012 07:50:45
The patch seems to work just fine. This same problem exists for exceptions specifications: bulleted entried in the "Raises:" section need to be treated the same as arguments. (edit: bulleted exceptions seemed broken at first, but now they seem to work...mysteries.)
My arguments for supporting this syntax are (in bullet form, of course):
- It may be found in existing code bases, so cartouche will be easier to use if it accepts the bullets. Liberal on input, strict on output.
- My editor deals with the bullets better, it seems. It knows about indentation and stuff when they're present. Granted, I could probably make it understand google-style, but I'm lazy.
- I personally find it easier to read the bulleted form. That may just be habit, but that's the way it is.
If you want to emit a warning (optionally?) when you encounter this syntax, that's fine with me.
If you ultimately decide to not support this syntax, I'd really appreciate better diagnostics. As it is, each cartouche failures turn into bug hunts, and that's pretty lame.
from cartouche.
From [email protected] on June 29, 2012 06:49:16
Better diagnostics are certainly required throughout.
I think I might go with a fourth option, which is to have this syntax supported by cartouche, but disabled by default. I would make an optional available which could be enabled in conf.py.
from cartouche.
From [email protected] on June 29, 2012 20:17:42
This issue is fixed by changelist cc63a876a994 and prior commits.
Both the Args and Raises blocks now optionally support bulleted lists using any of the standard reStructuredText bullet characters. To enable support for these behaviours in your documentation add the following to your conf.py:
-- Options for cartouche --------------------------------------------
cartouche_accept_bulleted_args = True
cartouche_accept_bulleted_raises = True
from cartouche.
Related Issues (15)
- qualified exception names trigger an invalid syntax exception HOT 1
- Missing argument name causes failure HOT 1
- UnboundLocalError: local variable 'arg' referenced before assignment HOT 1
- Support class docstrings HOT 1
- "Invalid hieroglyph argument syntax" error message could be more informative. HOT 1
- Support a Usage: block HOT 2
- Args with explicit modules and dots in type specifier do not parse HOT 1
- Parse errors do not report file or line number or line contents causing error. HOT 1
- setup.py imports code that tries to load sphinx
- cartouche not parsing multi-line exception syntax HOT 2
- nosetests explodes on setup function
- Bump version and upload to pypi? HOT 3
- broken in Python 2.X due to print not being a function HOT 2
- Multiline Raises blocks lead to lots of blank lines before Usage block
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 cartouche.