motivation for new contributors

[pubpub-zz]

I've just discovered this on PIL project:
"maybe we should add a badge for it too."

Could it be a good idea for us ?

[stefan6419846]

I personally do not think that this adds much benefit or motivation for new contributors unless they are already planning to contribute.

[j-t-1]

Ideas to help contributors

1. Reduce the cyclomatic complexity of the more complicated functions.
2. Move all references to PDF 2.0 (ISO 32000-2) so that we are reading from the same page.
3. Continue to follow the standard; we do this well, although there are exceptions such as PDF file identifiers.
4. Have an extensive "real world" example of using pypdf in the documentation (Read the Docs).

[stefan6419846]

Thanks for your feedback.

Reduce the cyclomatic complexity of the more complicated functions.

Martin recently opened some PRs about this, but as with quite some old code and complex error handling, this is no short-term task. Nevertheless, I personally consider such refactorings a task which could be done by interested contributors as well.

Move all references to PDF 2.0 (ISO 32000-2) so that we are reading from the same page.

I consider page numbers to be non-essential. While the PDF 1.7 standard is publicly available, access to the PDF 2.0 standard is restricted to users who provide their personal data in exchange.

Continue to follow the standard; we do this well, although there are exceptions such as PDF file identifiers.

Especially such aspects would be something to be properly documented as issues to work on these. Not everyone has read the complete PDF specification and remembers every detail by heart to directly stumble upon such aspects.

Have an extensive "real world" example of using pypdf in the documentation (Read the Docs).

It clearly depends on what "real world" means to you. I personally prefer standalone snippets which cover the most important features and document/explain some special cases and provide recipes accordingly. Even for me, I have at least five different use-cases (depending on the project) with different requirements.

[j-t-1]

Thanks @stefan6419846.

1. For the reducing complexity, thanks @MartinThoma for already doing this kind of improvement. If ever a todo list is created the functions or files that need simplifying could be added to formalize this process.

2. PDF 2.0 has been out for seven years, and the upside for using it exclusively in the documentation is for simplification and that only it contains things like deprecations and clarifications. There is a downside that you mention, but anyone using an older version could find out manually corresponding sections (although not ideal).

3. If a todo list is made, there could be a section on standards compatibility.

4. For the suggestion of "real world" examples, it probably would be better standalone snippets, as then they are much easier to find. So here is a revised version: Increase the pypdf documentation (Read the Docs), having more and better examples.