search

numenta / nupic-legacy

Numenta Platform for Intelligent Computing is an implementation of Hierarchical Temporal Memory (HTM), a theory of intelligence based strictly on the neuroscience of the neocortex.
http://numenta.org/
GNU Affero General Public License v3.0
6.34k stars 1.56k forks source link

Write a docstring checker for python source files #1207

Open syl20bnr opened 10 years ago

syl20bnr commented 10 years ago

I propose to write a little tool to check the documentation of the python source files. Some features which may be interesting:

I am a volunteer to code such a tool.

rhyolight commented 10 years ago

Would this be a git hook?

syl20bnr commented 10 years ago

Could be. I just checked nupic.tools and it is a good place for this kind of tool. My first thought is to make a python script using the inspect module to introspect the code and implement the check rules. @rhyolight What do you think about a validator calling the python script in nupic.tools ?

rhyolight commented 10 years ago

It gets tricky with nupic.tools as the validator, because the repository being validated must be checked out locally alongside the running tooling server and a shell script needs to be run to do the validation. The script must checkout the SHA being validated via raw git commands, then run the logic that does the validation and return the right exit code back to the web server.

I have a couple of necessary processes doing things like this in nupic.tools for other tasks (like push events to master branch defined in the config), but not for validations. I hesitate to add more of this type of thing because it's messy and I'd like to figure out a way to get rid of it entirely (see https://github.com/numenta/nupic.tools/issues/94).

My suggestion would be to drop a script into /scripts/validate_docstrings.py (or something like that) that writes a report about inadequate docstrings. The exit code should indicate success. Once that is in place, we can decide how exactly we'll use this tool. My gut feeling is to put it into the travis-ci build after running tests. Hopefully you can keep the runtime of this script down to a few seconds?

syl20bnr commented 10 years ago

@rhyolight You're right, let's make it a build step of the travis pipeline. I expect this tool to be very fast, should run << 1 second

rhyolight commented 10 years ago

:+1: