Openpyxl is missing some documentation to assist new developers in making contributions
Currently, the barrier to entry to contributing to openpyxl as a new developer is quite large because:
Related to source control:
- openpyxl is hosted on foss.heptapod and not github (not such a large one, as it's just GitLab but does mean people might not bother to make an account or might not find it when they search on github etc.)
- openpyxl uses Mercurial instead of Git and requires another package to be installed with pip called hg-evolve
- Mercurial/hg uses "topics" instead of branches and you cannot fork the repo, you have to clone and then use a topic
- Mercurial/hg uses some different commands than git
Related to the library itself:
- It's quite a large library, with a lot of interconnected parts, so it takes a while without some sort of
ARCHITECHTURE.MD
file (common on Github) to figure it out on your own. With each new developer figuring it out on their own, that's a lot of waste and a barrier to entry - Without reading section 8.13 of Python Cookbook 3rd Edition it can be hard to understand what all the classes and inheritance and mixins etc. are achieving in order to Serialize and De-serialize XML.
Related to Excel files themselves: (Speaking only about the post 2007/10 .xlsx and .xlsm varieties)
- The Specification for the Open XML file format is pretty dry: http://www.ecma-international.org/news/TC45_current_work/Office%20Open%20XML%20Part%201%20-%20Fundamentals_final.docx
- You need to understand how the manifest, rels, uuids, namespaces etc. all work together to store an excel workbook (with all its worksheets, images, charts etc.) into XML and in some case binary formats.
In order to address this, I propose the following ideas:
- Create an
ARCHITECHTURE.MD
(or .rst if needed) document, to explain how the library itself, is organized- with parts about the Serializable, and Typed classes etc.
- Create an
OPEN_XML_FILE_FORMAT.MD
(or .rst if needed) document, to explain the basics of the manifest, the rels, the workbook, the worksheets etc. and how they interlink. (also fundamentally, that this format is a zipped collection of files, mostly XML and some binary) - Add some more info and links to the
CONTRIBUTING.txt
file and/or thehttps://openpyxl.readthedocs.io/en/stable/development.html
file which is compiled fromdoc/development.rst
I believe.