Documentation fixes

[ljvmiranda921]

Documentation Task-List

• RST file for Inverse Kinematics
• Add citiation in the Pyramid topology to this paper
• Use command style in the doc string's "subject line"(PEP257)
• Update documentation and docstrings using http://www.hemingwayapp.com/ (Readability ~Grade 9)
• Merge (file merge, not git merge! 😆 ) basic_optimization example with **kwargs example (add RST file too)
• Note on large boundaries, etc. (see Applying large bounds results in a non-optimal solution and a Value Error #152)
• Note on precision and overflow (see Applying large bounds results in a non-optimal solution and a Value Error #152)
• Note on creating custom-objective function (return value should be (n_particles) see TypeError: 'bool' object is not subscriptable #109 )
• Update README (put Siobhan and Aaron as Collaborators).

[whzup]

I'm on the RST for Inverse Kinematics 👍.

[whzup]

What do you think about adding PEP257 conformity, @ljvmiranda921?

[ljvmiranda921]

I think our numpydoc convention for the docstrings is already good 😄 I find it easier to read and parse. Although I am not sure if we are talking about the same thing. Which parts do we need PEP 257-compliance?

[whzup]

Ok, I see. Just learned about PEP257 and thought we may use it 😄. I was especially wondering about this note:

The docstring is a phrase ending in a period. It prescribes the function or method's effect as a command ("Do this", "Return that"), not as a description; e.g. don't write "Returns the pathname ...".

It's the same as in the commit message subject line. I don't see the point in doing so, both variants seem fine to me but maybe you know why one would do that?

By the way, I try to make this repository more welcoming for first-timers. This has only partly to do with documentation. I found some nice sources for this to happen. Shall I open an issue where we can discuss this further?

[ljvmiranda921]

It's the same as in the commit message subject line. I don't see the point in doing so, both variants seem fine to me but maybe you know why one would do that?

Interesting, okay, you can add it on the checklist.

Shall I open an issue where we can discuss this further?

Hmmm... wanna discuss this first on gitter?

[whzup]

We should run flake8 once more before release 😄. Don't know if this belongs here, though. I don't know what some things do that flake8 wants to be changed so I'd rather give this to someone who knows what he's doing there 😆.