tldr; I'm strongly in favor of switching to Napoleon. I was not
previously opinionated on the matter, but after trying it out I see a
lot of benefits.

Reasoning: *We drown ourselves with useless information.*

    :param repo_name: The name of the repo
    :type  repo_name: basestring

This obviously has a very low information density.


In Napoleon this would be:

    Params:
        repo (basestring): Name of a repository

Format can't fix awkward, and this is still not a super helpful comment,
but at least it takes up less space but contains the same information.
The lists will be shorter and less visually assaulting. On the topic of
visual assualt, `:param:` is the first part of the line, which is where
I would rather be scanning for variable names.  **Napoleon presents
information in the order I look for it.**

Take a look at a comparison of larger docstrings from the wild:

_
__Current_

 def _process_repos(repo_objs, details, importers,
distributors):                                                                  
                                                                           

    
"""                                                                             
                                                                                
                                         

     Serialize repository objects and add related importers and
distributors if
requested.                                                                      
                                              

                                                                                
                                                                                
                                              

     Apply standard processing to a collection of repositories being
returned to a client.
Adds                                                                            
                                   

     the object link and optionally adds related importers and
distributors.                                                                   
                                                               

                                                                                
                                                                                
                                              

     :param repo_objs: collection of repository
objects                                                                         
                                                                              

     :type  repo_objs: list or tuple of pulp.server.db.model.Repository
objects                                                                         
                                                      

     :param details: if True, include importers and distributors,
overrides other
values                                                                          
                                            

     :type  details:
bool                                                                            
                                                                                
                         

     :param importers: if True, adds related importers under the
attribute
"importers".                                                                    
                                                   

     :type  importers:
bool                                                                            
                                                                                
                       

     :param distributors: if True, adds related distributors under the
attribute
"distributors"                                                                  
                                             

     :type  distributors:
bool                                                                            
                                                                                
                    

                                                                                
                                                                                
                                             

     :return: a list of serialized repositories with importer and
distributor data optionally
added                                                                           
                                

     :rtype:  list of
dicts                                                                           
                                                                                
                 

    
"""                                                                             
                                                                                
                                         


_Napoleon

_ def _process_repos(repo_objs, details, importers,
distributors):                                                                  
                                                                           

    
"""                                                                             
                                                                                
                                         

     Serialize repository objects and add related importers and
distributors if
requested.                                                                      
                                              

                                                                                
                                                                                
                                              

     Apply standard processing to a collection of repositories being
returned to a client.
Adds                                                                            
                                   

     the object link and optionally adds related importers and
distributors.                                                                   
                                                               

     
     Args:
          repo_objs (list or tuple of Repository): collection of
repository
objects                                                                         
                                                                              

          details (bool): if True, include importers and distributors,
overrides other
values                                                                          
                                            

          importers (bool): if True, adds related importers under the
attribute
"importers".                                                                    
                                                   

          distributors (bool) if True, adds related distributors under
the attribute
"distributors"                                                                  
                                             

    
     Returns:
                                                                                
                                                                                
                                

         A list of serialized repositories with importer and distributor
data optionally
added                                                                           
                                

     """                        




On 10/17/2016 03:41 PM, Patrick Creech wrote:
> On Mon, 2016-10-17 at 11:14 -0400, Sean Myers wrote:
>> I'd love it if we could stop writing docs in the ":param foo:" style. 
>> Instead,
>> I think that we should use the sphinx extension "napoleon" to write 
>> docstrings
>> that are *way* more human-readable (in my opinion, at least) while still
>> generating good sphinx docs.
> I, personally, am not a big fan of the ":param foo:" syntax.  To me, it puts 
> way to much information
> spread across multiple lines, increasing the length/scrolling/brainpower 
> needed to parse such an
> item.  I have to read multiple lines just to figure out what type  a variable 
> has.  Assuming
> separation between the params for clarity, you can easily take up 3 lines of 
> information for a
> single piece of data.
>
>> I think Napoleon's page in the sphinx docs explain this pretty well:
>> http://www.sphinx-doc.org/en/stable/ext/napoleon.html
> I really like this format, surprisingly.  You go to the args section, find 
> your variable, then have
> the information you need.  I really like how compact and succint it is, and 
> it doesn't require me to
> go to a new line to get all the info I need for a variable.  Also, the 
> variable name is the first
> item on the line, making it easier to identify from a scanning perspective
>
>
>
>
> _______________________________________________
> Pulp-dev mailing list
> Pulp-dev@redhat.com
> https://www.redhat.com/mailman/listinfo/pulp-dev


Attachment: signature.asc
Description: OpenPGP digital signature

_______________________________________________
Pulp-dev mailing list
Pulp-dev@redhat.com
https://www.redhat.com/mailman/listinfo/pulp-dev

Reply via email to