Comments (7)
Hi @Laleee,
thanks again for reaching out
For me they get documented like any other parameter and are just as important
There is a not one consensus on how to document **kwargs
, as their types and uses can vary
For this, **kwargs
can be documented as the bundle (kwargs
/**kwargs
) or as each individual keyword (key
/keyword
) depending on their use
Due to the way this package handles kwargs, being the standard for documenting them is a little more of a grey area, it makes sense you might not see a reason to document them as a param, or at all
*args
are easier to just document as args
or *args
for the value and type that there may be several of
There could easily be a switch, such as --ignore-kwargs
and ignore-args
which wouldn't effect the program at all for those that don't want to pass that arg
I see more of a use case for ignoring kwargs, but I can easily implement this feature for args while I'm at it
I'll see what I can do, and thanks again!
from docsig.
Adding ignore arguments seems like a good idea
FYI: This formatting is also legitimate: mkdocstrings/pytkdocs@0133369
I'm not sure if it's supported but I just wanted to give you a head's up.
from docsig.
Hi @Laleee,
I've worked on the implementation, I'll push it soon after some tests
At the moment, with Sphinx/RST at least, args and kwargs are a little more ambiguous in the docstring than the signature
The implementation would likely make checks that passed originally, with documented args and kwargs, fail - could be potentially confusing. What are your thoughts on this?
Either way, I'll push this soon and you can try it out
Cheers,
Stephen
from docsig.
Hello @jshwi,
Trying to test this I found a bug related to the pre-commit configuration.
pre-commit-config.yaml
- repo: https://github.com/jshwi/docsig
rev: v0.33.0
hooks:
- id: docsig
name: docsig
entry: docsig
language: system
types: [python]
require_serial: true
args:
- "-i"
- "--ignore-kwargs"
I get an error:
docsig: error: unrecognized arguments: --ignore-kwargs
Then I tried manually and the version wasn't the latest. After the manual update (pip install -U docsig
), both manual and pre-commit worked.
This shouldn't be the case since I've specified the exact version in the pre-commit (I guess it should have it's own environment based on the yaml specification).
Can you check if this is due to bad integration?
Regarding the feature itself, everything seems to be working as expected so far. 🎉
Best,
Lazar
from docsig.
yup @Laleee, definitely something wrong there, bear with me, I'll see what's going on
from docsig.
Opened #50 for tracking
from docsig.
Hi @Laleee,
Almost went down the rabbit hole with #50
I thought it was an issue with the hooks file, turns out it was an issue with the documentation
I don't currently us pre-commit
, I find myself rebasing a fair bit instead
I'm more compelled to now though, as I learn more about it
The key language: system
is the problem
it will use your system PATH for the executable, and not the isolated pre-commit
environment (it won't even build the revision specified) so it's up to the user in this case to have the executable installed
That's why it was using an outdated version, if you didn't have the package installed at all it would have raised Executable docsig
not found
By using language: python
, this implicitly instructs pre-commit to use the build tool necessary, in this case
pip install .
and so it will build the revision cloned
I sort of borrowed the format from pylint
, which was the worst one I could have used, as it HAS to use your virtualenv installation to import the package to lint
I've updated this documentation
Thanks for spotting this one!
Cheers
from docsig.
Related Issues (14)
- args and kwargs are not recognized as generic arguments HOT 2
- Support for Numpy HOT 3
- Positional-only arguments not recognized HOT 3
- Support for Python 3.7.x HOT 4
- Parameter and return value is not correctly recognized HOT 8
- Feature request - pre-commit integration & links HOT 4
- Report when the parameter is spelled wrongly HOT 3
- Add linkable path
- False positive when return annotation is a string HOT 2
- Skip checking for one line docstings HOT 2
- `docsig -v` doesn't print version
- Issue with pre-commit integration
- Import error on `sphinxcontrib.napoleon` on Python 3.10.8 HOT 6
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 docsig.