[scribus] A new Scripter API documentation

[ale rimoldi]

Hi Scribusers

Over and over, I've heard complains about the Scripter documentation
(among other things, of course!).

Since the Scribus documentation is not really free, there was not much
I was willing / able to do.

Last week, I got one more critical voice on the API documentation, and
I've decided that it was time to see if it was possible to get to
something sane, by exporting the API from the docstrings.

The starting point was the "good old"

https://github.com/aoloe/scribus-script-collection/blob/master/export-api-doc/export-api-doc.py

the final result is

https://github.com/aoloe/scribus-script-repository/tree/master/export-scripter-api

that can be used to produce

http://impagina.org/scribus-scripter-api/

(yes, people also asked for the API help to be published in the web)

Yeah, no more undocumented commands!
Only one place where the command will be documented!

The final goal is to replace the hand crafted API help in the Scribus
help by a separated Help entry (that will provide more focused search
results).

If you have ideas on how to improve the script or the output, you're
welcome to comment in here or in the bug tracker

https://bugs.scribus.net/view.php?id=16213

or in the scribus-script-repository Github repository linked above.

For those who are willing to help out, I could need a hand for
improving the docstrings:

- modify all signatures in the docstrings to match the real Python
  signatures ("getAllObjects(page: int=None) -> list" instead of
  "getAllObjects(["page"]) -> list"
- fix the formatting that do not convert well to Markdown/HTML (like
  code snippets and lists)
- a unified way of marking depracated functions
- propose (and implement) name changes for functions that do not match
  the overall naming schema.
- generally, improving the docstrings to be more useful.

Have fun
a.l.e