[Python-ideas] Add an UML class diagram to the collections.abc module documentation

[Steve Barnes]

Can I suggest that rather than manually producing or tweaking, and later 
updating, the diagrams it might be better to spend a little time 
annotating the source code and possibly adding to extra configuration 
files so that a tools such as DoxyGen 
(http://www.stack.nl/~dimitri/doxygen/) with GraphViz can be used to 
extract the information from the source code, produce the dot files and 
then produce the diagrams in whatever the desired format is. Of course 
Sphinx with suitable plug-ins might be able to do the same - or will 
eventually be able to do so.

While the diagrams produced might lack the elegance of manually produced 
ones they would be much more useful as they would always be up to date 
due to being produced, and updated, automatically.

DoxyGen is an open source, cross platform, tool that can parse and 
diagram any of C, Objective-C, C#, PHP, Java, Python, IDL (Corba, 
Microsoft, and UNO/OpenOffice flavors), Fortran, VHDL, Tcl, and to some 
extent D. It is already in use in the wxPython Phoenix project to parse 
the wxWidgets C++ code so as to extract the interface details for both 
the documentation and implementation. It can also work with MSCGEN, DIA 
& PLANTUML.

I am attaching the diagram produced for the full inheritance of 
collections.abc as produced by doxygen/graphviz but I am sure that there 
are some options that could make this more readable/useful.

Steve

On 01/01/2018 20:39, Brett Cannon wrote:
> While I appreciate what you're trying to accomplish, Yahya, one thing I 
> would like to say is if we were to accept the diagram into the docs I 
> would prefer that there be a source file that isn't an image which we 
> can update with easily available software (e.g. like a dot file). 
> Otherwise updating the file will either be burdensome going forward or 
> we will simply have to drop the image at the first instance of needing 
> to update it because no one can or be willing to put in the effort (and 
> I'm thinking in 5 years, not soon while we can count on you to help).
> 
> On Sat, Dec 30, 2017, 08:12 Yahya Abou 'Imran via Python-ideas, 
> <python-ideas at python.org <mailto:python-ideas at python.org>> wrote:
> 
>     We can find very usefull class diagramm to understand the hierarchy
>     of the builtin Collection abstract class and interface in java.
> 
>     Some examples:
>     http://www.falkhausen.de/Java-8/java.util/Collection-Hierarchy-simple.html
>     <https://eur03.safelinks.protection.outlook.com/?url=http%3A%2F%2Fwww.falkhausen.de%2FJava-8%2Fjava.util%2FCollection-Hierarchy-simple.html&data=02%7C01%7C%7Cdcdf2c291d0c41499c5908d5515902ef%7C84df9e7fe9f640afb435aaaaaaaaaaaa%7C1%7C0%7C636504365089997045&sdata=tho3ojtiDKu5lqBo6cM2dRR%2BY4Cqv74WaM4W49NJjzc%3D&reserved=0>
>     http://www.falkhausen.de/Java-8/java.util/Collection-List.html
>     <https://eur03.safelinks.protection.outlook.com/?url=http%3A%2F%2Fwww.falkhausen.de%2FJava-8%2Fjava.util%2FCollection-List.html&data=02%7C01%7C%7Cdcdf2c291d0c41499c5908d5515902ef%7C84df9e7fe9f640afb435aaaaaaaaaaaa%7C1%7C0%7C636504365089997045&sdata=4h4aUHJH9CTV9RpeyrN5zfSetYIpK4sySNL2IE5aGBI%3D&reserved=0>
> 
>     But when I search about python's ABC, The more detailed I can find
>     are those from the book of Luciano Ramalho Fluent Python:
>     https://goo.gl/images/8JGjvM
>     <https://eur03.safelinks.protection.outlook.com/?url=https%3A%2F%2Fgoo.gl%2Fimages%2F8JGjvM&data=02%7C01%7C%7Cdcdf2c291d0c41499c5908d5515902ef%7C84df9e7fe9f640afb435aaaaaaaaaaaa%7C1%7C0%7C636504365089997045&sdata=FbbDEgIsHJcZ4oRwVusZkFcepCEjHo5JuOzaj5erFz0%3D&reserved=0>
>     https://goo.gl/images/6xZqcA
>     <https://eur03.safelinks.protection.outlook.com/?url=https%3A%2F%2Fgoo.gl%2Fimages%2F6xZqcA&data=02%7C01%7C%7Cdcdf2c291d0c41499c5908d5515902ef%7C84df9e7fe9f640afb435aaaaaaaaaaaa%7C1%7C0%7C636504365089997045&sdata=Uwy0pQygI1R6sgtAZ6qbJOTUG8fM%2Fr76iZFRagoaytA%3D&reserved=0>
> 
>     (I think they're done with pyreverse of pylint)
> 
>     They are fine, but I think we could provide some other more detailed
>     in this page:
>     https://docs.python.org/3/library/collections.abc.html
>     <https://eur03.safelinks.protection.outlook.com/?url=https%3A%2F%2Fdocs.python.org%2F3%2Flibrary%2Fcollections.abc.html&data=02%7C01%7C%7Cdcdf2c291d0c41499c5908d5515902ef%7C84df9e7fe9f640afb435aaaaaaaaaaaa%7C1%7C0%7C636504365089997045&sdata=FgeML0%2BLBwSmUnyEZnqZvpF4jAP94BKyKqCR5FOX138%3D&reserved=0>
> 
>     The table could be difficult to understand, a diagram help visualize
>     things.
> 
>     I've began working on it with plantuml and pyreverse, I'm joining to
>     this mail what I've done so far so you can tell me what you think.
>     _______________________________________________
>     Python-ideas mailing list
>     Python-ideas at python.org <mailto:Python-ideas at python.org>
>     https://mail.python.org/mailman/listinfo/python-ideas
>     <https://eur03.safelinks.protection.outlook.com/?url=https%3A%2F%2Fmail.python.org%2Fmailman%2Flistinfo%2Fpython-ideas&data=02%7C01%7C%7Cdcdf2c291d0c41499c5908d5515902ef%7C84df9e7fe9f640afb435aaaaaaaaaaaa%7C1%7C0%7C636504365089997045&sdata=AIRvO1pUs69rWu%2FbV7fZ7ab%2FvrhNnlgFjucXz4JaXSU%3D&reserved=0>
>     Code of Conduct: http://python.org/psf/codeofconduct/
>     <https://eur03.safelinks.protection.outlook.com/?url=http%3A%2F%2Fpython.org%2Fpsf%2Fcodeofconduct%2F&data=02%7C01%7C%7Cdcdf2c291d0c41499c5908d5515902ef%7C84df9e7fe9f640afb435aaaaaaaaaaaa%7C1%7C0%7C636504365089997045&sdata=jUd4UT9Usupz0chUJnItDXCd84PCZdCFkIkOQNmE6S8%3D&reserved=0>
> 
> 
> 
> _______________________________________________
> Python-ideas mailing list
> Python-ideas at python.org
> https://eur03.safelinks.protection.outlook.com/?url=https%3A%2F%2Fmail.python.org%2Fmailman%2Flistinfo%2Fpython-ideas&data=02%7C01%7C%7Cdcdf2c291d0c41499c5908d5515902ef%7C84df9e7fe9f640afb435aaaaaaaaaaaa%7C1%7C0%7C636504365089997045&sdata=AIRvO1pUs69rWu%2FbV7fZ7ab%2FvrhNnlgFjucXz4JaXSU%3D&reserved=0
> Code of Conduct: https://eur03.safelinks.protection.outlook.com/?url=http%3A%2F%2Fpython.org%2Fpsf%2Fcodeofconduct%2F&data=02%7C01%7C%7Cdcdf2c291d0c41499c5908d5515902ef%7C84df9e7fe9f640afb435aaaaaaaaaaaa%7C1%7C0%7C636504365089997045&sdata=jUd4UT9Usupz0chUJnItDXCd84PCZdCFkIkOQNmE6S8%3D&reserved=0
> 

-- 
Steve (Gadget) Barnes
Any opinions in this message are my personal opinions and do not reflect 
those of my employer.
-------------- next part --------------
A non-text attachment was scrubbed...
Name: class__collections__abc_1_1_collection__inherit__graph.svg
Type: image/svg+xml
Size: 105357 bytes
Desc: class__collections__abc_1_1_collection__inherit__graph.svg
URL: <http://mail.python.org/pipermail/python-ideas/attachments/20180102/1727f831/attachment-0001.svg>