[SPARK-4821] [mllib] [python] [docs] Fix for pyspark.mllib.rand doc

+ small doc edit
+ include edit to make IntelliJ happy

CC: @davies  @mengxr

Note to @davies  -- this does not fix the "WARNING: Literal block expected; none found." warnings since that seems to involve spacing which IntelliJ does not like.  (Those warnings occur when generating the Python docs.)
I think we still use `random` as the public module name, `rand` is only used internal.