Usage docs on github

[dfrankow]

I installed the module. When I look at the github docs, it says to run something to get docs. When I try to run that thing, it can't find gendoc.sh. So, now I have to chase down some doc tool.

It would be handy to have some simple usage docs on github in the README. What are the main function points, and how are they used? What do I have to import?

[dfrankow]

Using ipython and tab completion, I get this:

In [1]: import Levenshtein

In [2]: Levenshtein.
Levenshtein.apply_edit Levenshtein.inverse Levenshtein.median Levenshtein.ratio Levenshtein.subtract_edit
Levenshtein.distance Levenshtein.jaro Levenshtein.median_improve Levenshtein.seqratio
Levenshtein.editops Levenshtein.jaro_winkler Levenshtein.opcodes Levenshtein.setmedian
Levenshtein.hamming Levenshtein.matching_blocks Levenshtein.quickmedian Levenshtein.setratio

In [2]: Levenshtein.distance('app', 'add')
Out[2]: 2

It's a good start.

[jared-maguire]

👍 Can you please just add the docs to the repo? It's nice to install via PyPi -- having to clone the repo just for docs defeats the purpose.

[npdoty]

Indeed, it's extremely difficult to evaluate the module before using it if you have to clone, debug and run some code on your machine just to see the documentation. Maybe you could add a gh-pages branch with up-to-date documentation and then the README can link to static HTML so we can read the documentation online.

[fake-name]

I generated the docs, and plonked them in the wiki (I also patched the doc generation script for py3k, but that's a different issue).

The wiki breaks anchor tags, but the rest is there.

Apparently anyone can edit the wiki?

[ztane]

Apparently anyone can edit the wiki. I looked at the doc generation - I'd like to automatically generate the RST document for the source code, but so far I didn't find any good tool; maybe should modify the genextdoc to output rst only, and to generate the document on a setup.py command, and store the active version in the repository.

[ztane]

And as always, the documentation is and has always been available with the python builtin help() utility, pydoc Levenshtein and many more, if only the module is installed.

[fake-name]

@ztane - The docs being available once it's installed is irrelevant for all the cases being discussed here, namely determining if the module will do what one wants before installing it.

If you have decent docstrings, why not sphinx? Why are you rolling your own doc generator?

[ztane]

@fake-name for the first concern, I understand that. I am not the original author of the module, I took the pypi maintainership from an even lazier (greetings Mikko ;) previous maintainer to incorporate the Python 3 portability changes, so that our project can be installed from PyPI on Python 3.

There are many shortcomings in the current code that ought to be matched, least of which is the documentation. The other problems are: the module does not have a directory (that is, have Levenshtein/init.py, which is a serious packaging issue), and there is no python-only module for which the extension would merely be a speed-up.

The reason why David Necas has written the special documentation generator is that Sphinx does not support C extension modules at all (because it seems that no one ever in their right mind writes a C-extension only without a python-only counterpart) For now, I shall make an update the README.rst with a link to the documentation, and upload a new version, and look into the possibility of having the generated HTML documentation in the source tarball that I upload into PyPI.

[ztane]

Please see #12 too, documentation available in github.