Meet docstring standards

Pierre-Yves Chibon pingou at pingoured.fr
Thu Sep 12 09:04:03 UTC 2013


On Thu, Sep 12, 2013 at 11:20:15AM +0300, Frankie Onuonga wrote:
> I have attached a patch to assist us in meeting coding and
> documentations standards.

> From 7bbb222e2ef4592cedda5ea926057e497cad97de Mon Sep 17 00:00:00 2001
>      # SQLAlchemy
> -    """SQLAlchemy Path:Path to the sqlalchemy DB in the system """"
> +    """SQLAlchemy Path:Path to the sqlalchemy DB in the system"""
>      SQLALCHEMY_DATABASE_URI = 'sqlite:///' + os.path.abspath(DATABASE)

You're mentionning coding and documentations standards, to which are you
refering?
I'm asking because I do not know the one saying, 'no trailing space at the end
of a documentation sentence', but to be honest, I only know the one from sphinx
and I try to make my code follow the pep8 standards.

>  class ProductionConfig(Config):
> -    """Production Environment: The environmental values which are set for a machine that is being used in production. This disables the machine from displaying errors and warnings. Secret keys, backend passwords and the path/location to the database is also set here"""
> +    """Production Environment: The environmental values which are set for a\
> +        machine that is being used in production. \
> +       This disables the machine from displaying errors and warnings. \
> +       Secret keys, backend passwords and the path or location to the \
> +        database is also set here"""

If I like having lines below 80 characters, I disagree with the use of '\' in
documentation.
When generating the documentation using sphinx or something else, they will most
likely appear and they just decrease the readibility (at least imo).

My 2cts :)

Pierre
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 198 bytes
Desc: not available
URL: <https://lists.fedorahosted.org/pipermail/copr-devel/attachments/20130912/75515c03/attachment.sig>


More information about the copr-devel mailing list