Add a page for RPM Python API

[FrostyX]

We agreed that having examples as scripts in the RPM git repository would be ideal (syntax highlighting, the possibility to run them, etc) but for better discoverability, I would like to mention them even from the RPM website. This way they may be easier to find for people searching on Google or the website itself.

[FrostyX]

I couldn't figure out how to build the website locally so I am not sure if the render will look pretty. But the markdown is IMHO valid.

[pmatilai]

Having a separate page of our own for Python and linking to the examples is fine, but showing output of those examples there makes no sense - somebody looking for rpm python API docs isn't interested in example program output but actual API documentation, and its examples.

[FrostyX]

Thank you for the review @pmatilai,

somebody looking for rpm python API docs isn't interested in example program output but actual API documentation, and its examples.

I agree, that's why my original idea was to put those examples directly into the documentation website. But I only partially agree with the "not being interested in the example program output" ... If I am completely new, I want to know what the API can do and seeing what kinds of information can be printed by the API and how it looks like before diving into reading any code is definitely helpful.

Almost all my usages of the RPM Python API went the same way.

1. I have a package name and I need to print its summary
2. I know it is possible because rpm -qi hello can show it
3. How do I get the same value in Python

Easily finding in the documentation that there is an example Python script, which prints the same information as rpm -qi is IMHO very helpful.

Having a separate page of our own for Python and linking to the examples is fine

But the examples aside, I talked with @xsuchy and we agreed that those web archive links used to be useful back in the day when they were up-to-date. What if took them, fixed any outdated information and put hem into the python.md page?

[pmatilai]

Sample output is meaningful when it's next to the actual code, but it doesn't work when linking to some far-away thing.

The problem here starts right at the bottom: API documentation needs to be where the code is, otherwise it'll fall out of sync. That's one of the reasons I prefer examples in the codebase itself too. I think what you're making here is more like a tutorial, which is a little different again. What the Python API really needs is

• export rpm module pydoc on the web
• make the module documentation meaningful (as in, add relevant usage examples)
• add a tutorial that refers the actual API docs

I'm certainly not expecting you to do all that, just thinking out loud as to what sort of structure we'd want/need here.
I think we'd want that one top-level python.md page just for general info and place to add links to, and then a separate subdirectory for the tutorial part, named thus.

[FrostyX]

I converted the whole "Chapter 16. Programming RPM with Python" from this archive
https://web.archive.org/web/20220628164347/https://docs.fedoraproject.org/en-US/Fedora_Draft_Documentation/0.1/html/RPM_Guide/ch-rpm-programming-python.html
into markdown. The text is unchanged. Now I want to go through it and modernize the outdated parts.

Can you please let me know how to build the rpm.org page locally? I want to make sure the markdown renders as expected.

[ffesti]

OK, this is only mentioned in the main RPM repository: https://github.com/rpm-software-management/rpm/tree/master/docs

https://docs.github.com/en/pages/setting-up-a-github-pages-site-with-jekyll/testing-your-github-pages-site-locally-with-jekyll explains how to do that. On Fedora I use rubygem-jekyll and friends to limit the amounts of gem downloaded directly.

[ffesti]

OK; added a README file for this repo.

[FrostyX]

@ffesti thank you very much. I did not realize that this is a jekyll project. I successfully built it through jekyll serve.

[ffesti]

Well, it is and it isn't. It's a GitHub pages project. GH pages uses something not completely unlike Jekyll - maybe.

[FrostyX]

I did my best to modernize the original "Chapter 16. Programming RPM with Python" documentation from
https://web.archive.org/web/20220628164347/https://docs.fedoraproject.org/en-US/Fedora_Draft_Documentation/0.1/html/RPM_Guide/ch-rpm-programming-python.html

It's not perfect but IMHO it is good enough. There are two FIXME entries that I would like to fix before merging but I couldn't figure out how it should be done. Can you please take a look?

[FrostyX]

The code uses file_h.dsOfHeader(), I don't know what should be done instead. I know a syntax like rpm.ds(h, rpm.RPMTAG_PROVIDENAME) but it takes an argument, the original example doesn't. I was thinking of rpm.ds(h, rpm.RPMTAG_EVR) but then .EVR() on it returns nothing. So I don't know.

[FrostyX]

The original example used this undefined resolved variable. I have no clue how it should be set so that the example makes sense.

[FrostyX]

This is the same undefined resolved variable but in a full script example