Improve Documentation

[GoogleCodeExporter]

This will probably just be a permanent entry in the issue tracker :), but...

Passlib's documentation could definitely be improved. It's currently organized 
like a reference manual, with snippets of narrative scattered throughout. 
Furthermore, some bits of the reference go further into the internals than 
users probably care about. 

Hope to improve things a little for the 1.6 release, but it will probably be an 
ongoing issue. Would like to do something which better separates the 
narratives, the public reference, and the internals. 

Original issue reported on code.google.com by elic@astllc.org on 13 Mar 2012 at 5:31

[GoogleCodeExporter]

Documentation restructured for 1.6 release. Cleaned up password hash api, 
rewrote CryptContext docs into walkthrough & reference pages. Added cross 
links, and a better front page. 

Original comment by elic@astllc.org on 1 May 2012 at 9:03

• Changed state: Started

[GoogleCodeExporter]

Not sure if you want to document backwards compatible passlib usage (or add 
release numbers when sth appeared/disappeared to the reference), but here are 
some pointers what I encountered while integrating passlib 1.3 .. 1.6.1 usage 
for MoinMoin 1.9.x:

http://hg.moinmo.in/moin/1.9/rev/25900eaeb864#l5.17 (see KeyError)

http://hg.moinmo.in/moin/1.9/rev/25900eaeb864#l5.51 (see "auto" - it would be 
nice to have this info "new in 1.6" in the reference docs)

http://hg.moinmo.in/moin/1.9/rev/25900eaeb864#l6.154 (backwards compat hack)

hg.moinmo.in/moin/1.9/rev/25900eaeb864#l6.154 ("new in X.X" missing in the 
reference, found it out by looking at different releases' code)

Much stuff was mentioned in the ChangeLog somehow, though.

Thanks a lot for passlib! I like it, it is nice to use.
Guess I'll kick out all our legacy pw code in moin2 and just use passlib. \o/

Original comment by Thomas.J...@gmail.com on 19 Jan 2013 at 1:32

[GoogleCodeExporter]

Glad it's proving useful! 

Thanks for the feedback... I definitely want to document backwards 
compatibility issues, etc; and I'm only now coming to appreciate how slowly new 
releases make their way through the open-source ecosystem :)

For Passlib 1.7, I'm planning on reformatting the Release History page to have 
clearly named "Backwards Incompatibilities" sections, ala Pyramid's "What's 
New" page 
(http://docs.pylonsproject.org/projects/pyramid/en/latest/whatsnew-1.4.html). 

In the mean time, I've gone ahead and done some quick-fixes to the points you 
identified...

* KeyError, etc - I've added a section detailing all the errors thrown by the 
CryptContext constructor - 
http://packages.python.org/passlib/lib/passlib.context.html#configuration-errors

* deprecated="auto" flag - added "new in 1.6" note.

* needs_update() - The documentation should hopefully now be clearer about the 
name change. Also, I bumped hash_need_updates()'s removal date forward to 
Passlib 2.0 -- that part of the API is a little too public to go from 
deprecated->removed in just two releases. 

Let me know if there's anything else that's unclear - I'm using passlib's 
documentation as an excuse to get better at technical writing, among other 
things :)

Original comment by elic@astllc.org on 19 Jan 2013 at 8:58

[GoogleCodeExporter]

http://packages.python.org/passlib/password_hash_api.html#support-methods typo 
"hexidecimal"

Original comment by Thomas.J...@gmail.com on 19 Jan 2013 at 9:19

[GoogleCodeExporter]

http://pythonhosted.org/passlib/lib/passlib.ext.django.html#module-passlib.ext.d
jango typo "controled"

Original comment by Thomas.J...@gmail.com on 27 Mar 2013 at 1:47

[GoogleCodeExporter]

note: I am working on a patch that fixes above and lots more typos.

Original comment by Thomas.J...@gmail.com on 27 Mar 2013 at 3:50

[GoogleCodeExporter]

here's the exported changeset for the typo fix, see attached file.

Original comment by Thomas.J...@gmail.com on 28 Mar 2013 at 10:01

Attachments:

• typo.diff

[GoogleCodeExporter]

Thanks for the cleanup effort! I have a blindness for certain words, 
particularly hexadecimal :)

Integrated typo.diff as revision 1f5b8860b743.

Original comment by elic@astllc.org on 10 Apr 2013 at 6:28

[GoogleCodeExporter]

more docstring fixes, issues found by pycharm.

Original comment by Thomas.J...@gmail.com on 11 Apr 2013 at 1:28

Attachments:

• docstr_fixes.diff

[GoogleCodeExporter]

I've decided having "improve documentation" as a permanent entry in the issue 
tracker was probably a bad idea that I had, since it ruins granularity of 
tracking specific issues. The previous patches have already been integrated 
into the default branch for release as part of passlib 1.7, so closing this 
issue down.

Thanks for the contributions!

- Eli

Original comment by elic@astllc.org on 27 Dec 2013 at 9:13

• Changed state: Done