#apidoc

[whiskeychocokeopi-blog]

How to fix support for password authentication was removed on GitHub

Understanding how to configure and use Access Tokens in GitHub

Shout out to Giorgos Myrianthous for his article on Medium. I found his article helpful. Spot on to fix the issue. Thank you.  

[venel-me]

Nested Resources

So far I have put in over 27 hours into my rails finale application before I ran into a troublesome error. I figured it would have to do with my routes since its an error stating 

  "No route matches ..... missing required keys: [:id]"

so I did what developers do best, look at the new error for about 10 minutes, then changes this up. I dibble and dabbled with it for a good 20 minutes before I went running back to the ROR guide

Talk about being blown away! at a first glance this seemed to be an easy fix. So I assumed(making a fool out of yourself) and went to work, forgetting to note that, I had to manually change all my paths for that model after nesting it. Please don't think I am complaining, well maybe a little bit. At the end, of the day, nested resources actually saved me a lot of time by doing a lot of the relational ties & connections for the models. I am actually eager to dive right back in, learning what else I can unfold.

[scott-bamford]

Flexible API Documentation with ApiDoc (http://apidoc.codeplex.com)

What is ApiDoc

ApiDoc is a tool for creating a set of technical API documents to help developers…

View Post

[eatdev]

Python decorators, docstrings and Sphinx

I've been writing a fair bit of code lately, and decided to take a break and do some documentation.  I decided to use Sphinx to autogenerate HTML documentation from python docstrings.

It works pretty well, except I noticed there were key methods that did not show up in the auto-generated documentation.  Comparing them against the methods that appeared properly quickly revealed that somehow methods that had a decorator did not show up.

A search on StackOverflow gave a good description of the problem.  Essentially, Sphinx uses introspection to check function.__name__ and function.__doc__ to pull out the docstring.  A function decorator creates a new function from your code, and the new function has its own __name__ and __doc__.  So in your decorator, you need to ensure that you copy the original function's __name__ and __doc__ to the function created by your decorator.  functools.wraps() simplifies this.

My solution wasn't quite so simple.  I had used a class decorator instead of a function decorator.  Simply copying __name and __doc__ over didn't work, since the class decorator returns a class instead of a function, and Sphinx was looking for functions to document.  It looks like the solution to this is to wrap the class decorator inside a function decorator.  I didn't strictly need to use a class decorator, so I rewrote it as a function decorator and things went along ok.

I'm glad I had a nice suite of testcases to verify that rewriting the decorator didn't break anything.  Starting to become a big fan of Test Driven Development.